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IMPORTANT INFORMATION: If haven't yet mastered the basic 
functions of Apple Writer, you might find yourself confused by what 
you read in this manual. That's only natural: reading about WPL 
without having learned Apple Writer is like trying to bake brownies 
when you've never used a stove before! Save yourself from the frus- 
tration of burned brownies: don't pick up this book with any serious 
intent until you feel comfortable with Apple Writer. 

This manual gives you the power to automate word processing by 
writing programs in a Word Processing Language (WPL). WPL is 
a special feature of Apple Writer III. Before reading further, please 
be sure you are familiar with the contents of the Apple Writer III 
manual (which will be referred to from now on as the "Apple Writer 
manual"). You might want to read Appendix B in the Apple Writer 
manual right now. It takes you through an example of how to use 
a WPL program; in this manual you will learn how to write your 
own programs. 

How to Use This Manual 

If you already know how to program in another computer language 
(such as BASIC, FORTRAN, Pascal, or assembly language), you will 
be able to learn WPL very rapidly. In fact, you may not need to read 
all of this manual. To determine whether you need to read the 
manual, turn to the appendixes. There you will find the rules for 
writing WPL statements and the rules for using each WPL command. 
The appendixes may provide all you need to know in order to begin 
using WPL. On the other hand, if you'd like more detailed informa- 
tion, read or skim the manual to see how WPL differs from the 
computer language you already know. 

If you are new to computer programming, you will discover that 
WPL is a very easy language to learn. Begin with Chapter 1 and read 
through the whole manual. Right away you will learn programming 
terminology and many fundamental programming concepts. You will 
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be able to automate simple word processing functions by the time 
you finish Chapter 2. As you read further in the manual, you will 
become familiar with more WPL commands until you have mastered 
the entire language. 

The best way to master automated word processing is to work 
with the sample programs in this manual. As you read each chapter, 
study the sample programs line by line so that you understand what 
each statement does. Type the programs exactly as they appear in 
the manual— you'll learn a lot about WPL statements that way— 
and save them. Then run the sample programs and experiment with 
them. The more you do, the sooner you'll be speaking WPL like 
a native. 

Here is an annotated list of the chapters and appendixes in this 
manual: 

Chapter 1 Introduction to WPL: Provides a conceptual over- 
view of WPL. 

Chapter 2 How to Write in WPL: Explains the rules for writing 
WPL statements. 

Chapter 3 Controlling Execution: Describes various ways to 
tell WPL which statement to execute next. Shows 
how a statement may be executed or not depending 
on some condition. 

Chapter 4 Output: Shows how to send output to disk, screen, 
and printer from a WPL program. 

Chapter 5 Using String Variables: Teaches how to use string 
variables— special symbols that stand for text. 

Chapter 6 Using Numeric Variables: Teaches how to use 
numeric variables— special symbols that stand 
for numbers. 

Chapter 7 Advanced Techniques: Describes how to write very 
large programs; explains how a WPL program can 
execute another WPL program; tells how to make 
and use a STARTUP program; teaches how to load 
the catalog into memory. 

Chapter 8 Enhancing WPL Programs: Shows how to modify 
the standard WPL programs that come with 
Apple Writer. 

Appendix A Syntax of WPL Statements: Summarizes the syntax 
of WPL statements. 
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Appendix B List of WPL Commands: Lists WPL commands in 
alphabetical order. 

Appendix C Summary of WPL Commands by Function: Lists 
WPL commands by function; gives syntax of each 
command and examples. 

Appendix D Error Messages and Debugging Hints: Lists and 

explains WPL error messages; provides debugging 
(error identification) hints. 

Appendix E Answers to Programming Questions: Contains 

answers to the programming problems presented in 
this manual. 

Appendix F WPL Programs in This Manual: Lists and describes 
all of the sample programs that appear in 
this manual. 
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WPL gives you a way of doing many exciting things with Apple Writer; 
you can 

• create custom reports, 

• write individualized form letters, 

• do arithmetic calculations, 

• perform repetitive Apple Writer functions, 

• create your own menu programs, 

and much more. 

This chapter tells you about the relationship between Apple Writer 
and WPL. It also shows you how much you already know. 



WPL is a feature that makes Apple Writer more powerful and easier 

to use. WPL has some special commands that you'll learn about in 
You already know how to write a wpl this manual. But you could write an entire program right now, using 
program! j ust tne Apple Writer commands you've already learned to use. Most 

of the commands you learned in Apple Writer can be used in 

WPL programs. 



An Example of a WPL Program 

Here's an example of a program you already know how to write. It's 
called wpl . MEMOPRT and it's on your UTILITIES disk. 



you do anything else, it's a good idea to make an extra copy of 
iisk. Once you have a backup copy, put the original 
i and use the backup copy for the exercises in 

this manual. 




An Example of a WPL Program 



WPL.MEMOPRT automatically prints the heading and body of 
a memo. Be sure your printer is turned on. Then start up your com- 
puter with the MASTER disk, insert the UTILITIES disk, and run the 
program by pressing [p] and then typing 



do .dl/wpl .memoprt 



The program is shown below in the lefthand column. The middle 
column contains the command name as you are used to seeing it in 
Apple Writer. Explanations of what each command does appear in 
the righthand column. 



program 



Apple Writer 
command 



what it does 



MEMOPRT NY [N]Y 

L .Dl/HERDING [l] 

PNP [P]NP 

NY [N]Y 

L .D1/B0DY [L] 

PCP [P]GP 



clears text buffer 
loads document 
prints document 
clears text buffer 

loads second 
document 
prints second 
document 



You'll notice that although you recognize all the commands in this 
program, they look somewhat different from the format you're used 
to seeing them in. Chapter 2 explains how to write any Apple Writer 
command you already know in this new format so you can use it in 
a WPL program. 

There's one thing you need to be clear on to become a successful 
WPL programmer: that is, programming is easy! All you need is to 
be able to follow instructions, think through a problem step by step, 
pay attention to details, and learn from your mistakes. 



How WPL Is Related to Apple Writer 

Apple Writer and WPL are really both part of the same overall word 
processing system. WPL builds on commands and procedures you 
already know from Apple Writer, but WPL has some differences and 
many additional features. 



Immediate, Embedded, and Deferred Commands 

In Apple Writer you learned about two kinds of commands: 
immediate and embedded. In WPL there are immediate and embed- 
ded commands and a third kind of command as well: deferred. 
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Immediate commands cause something to happen right away. For 
instance, as soon as you type this immediate command 

[S] f i lenarne 

the computer immediately saves your file. 

Table 1-1 shows all of the immediate commands you've learned in 
the Apple Writer manual as they appear in Apple Writer and as they 
appear in a WPL program. 

Table 1-1. Immediate Commands In Apple Writer Meaning In WPL 



[6] 


Beginning 


B 


[C] 


Case Change mode 


C 


M 


Direction arrow 


D 




End 


E 


[F] 


Find and replace 


F 


[G] 


Glossary 


G 


[L] 


Load 


L 


[N] 


New 


N 


[o] 


SOS Command Menu 





[PJ? 


Print/Program Menu 


p? 


[o] 


Additional Functions Menu 





[5] 


Save 


s 


[T] 


Tabs 


T 


[w] 


Word delete/retrieve 


w 


[ ] 


Paragraph delete/retrieve 


X 


[v] 


Splits screen 


Y 


[2] 


Word wraparound 


z 



The immediate commands [R] (Replace) and [v] (Control Character 
Insertion mode) cannot be used in a WPL program. 

Embedded commands are those that you insert in your document. 
They aren't executed right away. Apple Writer pays no attention to 
them when you put them in your document. When you print the 
document, Apple Writer finds and executes the embedded 
commands in the course of printing. 
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In general, embedded commands have to do with determining how 
your document is printed. The Input command, an especially useful 
embedded command, stops the printing of a document and waits 
for your input. For instance, if you want Apple Writer to remind you 
to tighten the platen before a subscript or superscript command, 
you embed this command in your document: 

. IN Tighten the platen ! 

When Apple Writer comes to this command, it will display 

Tighten the platen ! 

on the screen and wait for you to press (return before continuing 
to print. 

Table 1-2 shows all of the embedded commands you've learned in 
the Apple Writer manual as they appear in Apple Writer and as they 
appear in a WPL program. As you may recall from the Apple Writer 
manual, most of the commands in Table 1-2 can also be used as 
immediate commands (that is, without the leading period). 
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Table 1-2. Embedded Commands 

In Apple Writer Meaning In WPL 



- LN 


Left Margin 


PLM 


.PHI 


Paragraph Margin 


PPM 


.Phi 


Right Margin 


PRhl 


. TM 


Top Margin 


PThl 


-BM 


Bottom Margin 


PBhl 


.PN 


Page Number 


PPN 


.PL 


Printed Lines 


PPL 


.PI 


Page Interval 


PPI 


.5P 


Single Page 


PSP 


.CR 


Carriage Return 


PGR 


.UT 


Underline Token 


PUT 


.LJ 


Lett Justify 


PLJ 


.FJ 


Fill Justify 


PFJ 


.CJ 


Center Justify 


PCJ 


.PJ 


Right Justify 


PRJ 


. TL 


Top Line 


PTL 


- BL 


Bottom Line 


PBL 


.IN 


Input 


PIN 



The embedded commands ..FT (Formfeed), and .ep (Enable Print) 
cannot be used in a WPL program. 
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A deferred command is one that is in a program; it is not executed 
until the program is run. Almost all of the commands that you learned 
in the Apple Writer manual can be used as deferred commands in 
a WPL program when they are written in a slightly different way. 
Here's what the [s], .in, and LM commands look like when written 
as deferred commands: 



s f i lename 

pinTighten the platen! 
pi ml 5 

You write a WPL program by making a text file of deferred 
commands like those above; then to run the program you press [p], 
then type 

do . d2/pr ogramnarne 



Figure 1-1. Music by WPL 



and press heturn ; . 



Using Apple Writer ' Hands Off" 

WPL gives you a way to use Apple Writer "hands off," just like playing 
a player piano. You can run WPL programs that someone else wrote 
just as you can use a player piano roll to play a song that someone 
else recorded. 



























JF 
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You can "play" a WPL program over and over again and it never gets 

tired. And your hands don't have to be on the keyboard— you can 

be busy doing other tasks (or resting from your labors) while WPL plays 




Let's look at this a little more closely. To create a player piano roll, 
you have to play the piano. Everything you play, wrong notes and 
all, is recorded exactly as you played it. To create a WPL player 
piano roll, otherwise known as a program, you type the Apple Writer 
commands almost as you would it you wanted them to be executed 
immediately. (Apple Writer knows that they're not immediate 
commands because you don't use the (control) key.) You complete 
the recording by [s]aving the commands in a file called, say, 
program, and you play it back by pressing [p], then typing 

do . dl/program 

and pressing (return) . 

There are a few special rules for typing commands that are part 
of a WPL program. The rules are called syntax and are covered 
in Chapter 2. 

The [P]rint/Program Option 

Some of the commands you've learned in Apple Writer are really 
WPL commands. Here's how to tell the difference. If you have to 

Commands that are preceded by [p] press [p] before issuing the command, it's a WPL command. 

are wpl commands. Remember that [p] gets you the [p]rint/Program option of Apple 

Writer; the print part of this option has to do with text format- 
ting, and the program part has to do with WPL. The WPL commands 
you know are 

do Do (execute or run a WPL program) 

np New Print (print the first or only file of a document) 

CP Continue Print (print the next file of a document) 

Now look again at the wpl . riEMOPRT sample program earlier in 
this chapter. Notice that the np and cp commands have a p in front 
of them. This stands for 'control; - p (which you are used to 
seeing represented as [p] in the Apple Writer manual). 

You will learn more about specific syntax requirements in Chapter 2. 
Right now the important thing to remember is that WPL commands 
are connected to Apple Writer through the [p]rint/Program option. 
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How WPL Shares Resources With Apple Writer 

Apple Writer is a program that can talk to other programs. For 
instance, Apple Writer passes your messages to the operating sys- 
tem every time you [L]oad or [s]ave a file. Apple Writer also receives 
messages from any WPL program you run. Therefore Apple Writer 
and the WPL program must be in the memory of the computer at 
the same time. You might think that things get fairly complicated 
inside the computer, but in fact Apple Writer has "a place for every- 
thing and everything in its place." That's what the rest of this chapter 
is about. 



How WPL and Apple Writer Share Memory 

Apple Writer and WPL each stay in special sections of memory 
assigned to them; these sections of memory are called buffers. The 
buffer assigned to WPL is 2,048 characters long. That's long enough 
to write quite a large WPL program, but it's not long enough to write 
any possible program, so there's a method called chaining that lets 
you connect several programs together. Chaining is described in 
Chapter 7. 

WPL programs and the footnotes in a document share the same 
buffer. So if you're using a WPL program to print a document that 
contains footnotes, you won't have as much room available for your 
program as you otherwise would. The room available for the WPL 
program will be reduced to 1 ,024 characters; the rest of the buffer is 
used to hold the footnotes. 



All of the other buffers that were described in the Apple Writer 
manual continue to exist when you run a WPL program. Figure 1-2 

Figure 1-2. How WPL Shares Memory shows how WPL Shares memory. 



1 




FOOTNOTE | 


WPL 


BUFFER J 


PROGRAM 



WPL BUFFER 



WPL 
PROGRAM 
2048 
CHARS 



WPL BUFFER 
WHEN THERE IS NO 
FOOTNOTE 



FOOTNOTE 
BUFFER 
1024 
CHARS 



WPL 
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WPL BUFFER 
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The screen buffer assumes special significance in WPL, so we'l 
look at that next. 
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How WPL and Apple Writer Share the Screen 



Remember that player piano? When you're playing the piano 
yourself— using Apple Writer in immediate mode— you usually want 
the screen to display all or part of the document in the text buffer. 
Occasionally you may load a document without putting it in the text 
buffer— that is, you display it temporarily on the screen. When you're 
using a player piano roll— a WPL program— you will scarcely ever 
want to display the document on your screen. There are three 
reasons for this: 



• first, your WPL program will run up to five times faster if you don't 
display the document as it's being processed; 

Turn the text display off in most wpl • second, you don't need to look at the text as it's being processed— 
programs. you a | re ady know how it will be processed, because you designed 

the program; and 

• third, there are other, more useful ways to use the screen. 



For a translation of the two-character 
name of any WPL command, see 
Appendix B. For a summary of how to 
use any WPL command, see Appendix C. 



The screen normally displays the contents of the text buffer. WPL 
has a command, nd, that turns off the text display, and another 
command, yd, that turns it back on. 

When the text display is on, WPL can send only a one-line message 
to the screen. When the text display is off, WPL can use the entire 
screen for messages. (See Figure 1-3.) 
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Figure 1-3. The Screen With and Without 
Text Display. 



Occasionally, you may load a document without putting It In the text buf fei — that Is. you 

display It temporarily on the screen. When you're using a player piano rol l--a WPL program- - you ul 1 1 

scarcely aver want to display a document on your screen. There are three reasons for this: 

-first, your U1PL program ul 11 run up to flue times faster If you don' t display the document as 
It's being processed; 

-second, you don' t need to look at the text as It 'a being processed- -you already know how It 
will be processed, because you designed the program; and 

-third, there are other, more useful uays to use the screen. 



With text display (YD), you see only one 
line of the message, and it's often hard 
to see. 



The screen normally displays the contents of the text buffer. WPL has a command. NO, that 
turns off the text display, and another command. 

Enter Your Selection (A-J) 

When the text display Is on. WPL can send only a one- line message to the screen. When the text 
display Is of f , WPL can use the entire screen for messages. (See F lgure 1-B ) 



Without text display (ND), you see 
messages on the whole screen. (The 
Help Screen Menu is a message from 
a WPL program.) 



Figure 1-3 A. 



HELP SCREEN MENU 

fl. Command Summary 

B. Cursor Movement 

C . Upper Louer Case Change 

D. Delete Retrieve Text 

E. Tabs 

F. Glossary 

G. Saving Flies 

H. LoadlngFlles 

I. Find Replace Text 

J. Print Format Commands 

Press RETURN to Exit 
Enter Your Selection (fl- J) 



Figure 1-3 B. 



By turning off the text display, you can create menus like those in 
Apple Writer or you can display the results of computations per- 
formed by your WPL program. You can also display information that 
Use your screen for debugging will help you debug your program. Debugging is a popular computer 

term. It means removing the errors, or bugs, from your program. 
See Appendix D for more information on program errors and on 
using the screen to debug programs. 

Now that you know how WPL and Apple Writer are related, you are 
ready to begin actually writing in WPL. Just turn the page. 
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A WPL program is a series of statements. Whether we refer to them 
as WPL statements or just plain statements, we mean exactly the 
same thing. Each statement represents a complete thought, just as 
an English sentence does. A statement usually occupies one line of 
text (that is, it begins and ends with a return ), although certain 
Apple Writer commands such as [F]ind may require a two-line 
statement. 

First you will learn what the parts of a statement are called and what 
they're for. Then you'll be shown how to make statements out of all 
the Apple Writer commands and WPL commands you already know. 

Syntax is the name for the collection of rules that describes how 
words in a sentence fit together. For instance, in English syntax the 
following order is usual: 

SUBJECT VERB OBJECT 

I threw the ball. 

The ball hit the fence. 

The only way to tell whether the ball is a subject or object in the 
second sentence is to study the word order. This chapter teaches 
you the simple syntax rules that apply to WPL statements. (See 
Appendix A for a summary of the syntax rules.) The rules help 
Apple Writer interpret your program correctly, without ambiguity; 
they also help you remember what you meant when you wrote it. 

Before we look at the details, though, let's look at the big picture. 



How to Write in WPL 



Overview of WPL 

This section 

• defines some terms that are used in this manual; 

• introduces you to two programming concepts: labels 
and comments; 

• gives you some general rules about when to use upper- and 
lowercase; 

• reminds you how to save and use a WPL program. 

Commands and Statements 

Command. This word means just what it does in the Apple Writer 
manual: an order given to the computer, like [F]ind or [p]np 
(New Print). 

Apple Writer Command. This is a command that you learned to 
enter as an immediate command by pressing the f control) key while 
typing the command letter. Apple Writer commands in a WPL 
statement are entered without using the control key. The 
command names are always one character long. Here are some 
Apple Writer commands: 

As Deferred Commands 
As Immediate Commands in a WPL Program 

[iT B 
[L] L 
[N] N 



WPL Command. This is a command that you learned to enter as an 
immediate command by pressing [p] before typing the command. 
In WPL, these commands are entered by preceding them with 
the letter p. The command names themselves are always two 
characters long. Here are some WPL commands: 

As Deferred Commands 
As Immediate Commands in a WPL Program 

[P]NP PNP 
[P]CP PCP 
[P]DO PDO 
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Statement. A statement, sometimes called a WPL statement, is like 
a sentence; it is a complete thought. The term statement generally 
refers to a statement that contains a command, but a statement may 
also be a comment, which is defined below. A command statement 
includes the command name, an optional label, and any other 
information supplied with the command. 

Labels 

Giving names to commands Labels are names. They tell Apple Writer which WPL statement in 

your program you're referring to. You've never had to do that before 
because you haven't needed to talk about a command— you could 
just execute it. But sometimes in a program you want to tell Apple 
Writer to go back and do a set of commands that it has already done. 
The way to do that is to give the first statement in the set a name; for 
example in the following program segment, NEWDGC is a label. 

NEWDQCL .D2/NENTEXT 
PGO NEWDOC 



Comments 

A comment is a note to yourself written in WPL syntax and included 
in a program. Comments, like labels, are things you haven't had any 
use for before. They're special statements that Apple Writer ignores 
when it executes your WPL program. Comments are there for the 
internal documentation sole purpose of helping you to remember how your program works. 

Then if you haven't looked at the program for six months you can 
read the comments to see what it does. The following statement is 
a comment: 

P Note that the latest version of the file must be loaded. 

(A comment always begins with a P. See the end of this chapter for 
more information on how to write comments.) 
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Uppercase and Lowercase 



Some of the WPL statements in this manual are printed in uppercase 
and others are printed in lowercase. Most of the time Apple Writer 
doesn't care which you use. pnp is exactly the same command as 
pnp or Pnp or even pNp. 

There are two places where upper- and lowercase definitely do 
Upper- and lowercase matter in labels. make a difference, however. The first has to do with labels: a label 

must be typed exactly the same way wherever it is used. If you use 
uppercase for a label in one place in your program and lowercase in 
another, Apple Writer will think you are talking about two different 
labels. This can lead to very strange program results. 

The other place where upper- and lowercase make a difference is in 
The argument follows the command and the argument of a WPL statement— the portion of the statement that 
gives more information about it. follows the command and gives additional information about it. 

(To find out more about arguments, see the section called "The Parts 
of a WPL Statement" later in this chapter.) A part of the argument 
may be intended to have a precise value in which upper- and lower- 
case are significant. For instance, if you ask Apple Writer to [r]ind 
/applet (the fruit), that's not the same as finding Apple - (the 
company). Here's the rule of thumb to follow in writing Apple Writer 
and WPL arguments: 

• If the argument must be a specific value, such as v or n, it can be 
entered in either upper- or lowercase. 

• If the argument may be any value, such as a string of text to be 
found or printed, then the argument is taken exactly as you 
typed it. 

■i^^H^H Editing and Saving a WPL Program 

A WPL program is a document that has been saved in a file. It is 
created the same way any Apple Writer document is created. 

To create a new WPL program, clear memory with the Apple Writer 
[N]ew command, type the program, and save it in a file using the 
Apple Writer [s]ave command: 

[S]ave: . dl/programname 



18 



Chapter 2: How to Write in WPL 



To edit an existing WPL program, use the Apple Writer [L]oad 
command to load the file: 



[l_]oad: . dl/programname 

Then edit it and save it. 

To use a WPL program that you have written and saved on a disk, 
press [p] and then type the WPL Do command followed by the 
name of the file you saved the program in: 

[P]rint/Program: do . dl- programname 

See Appendix F for a list of the programs All the sample programs used in this manual are found on the 
on the utilities disk UTILITIES disk; the program names all begin with WPL. 



Important: 

It's a good idea to start the names of all your WPL programs with WPL., 
like this 

upl .programname 

so that you can easily distinguish WPL programs from the rest of your 
files. 

■HHHHHHIH The Parts of a WPL Statement 

A statement always contains a command name (unless it is a 
comment statement); it may also contain a label (the name of the 
statement) and an argument (the additional information that is 
needed in order to execute the command). Figure 2-1 shows the 
syntax of a statement. 

Figure 2-1. Syntax of a WPL Statement. STATEMENT LOADFILE L .D1/FILENAME 



LABEL 






COMMAND 
NAME 






ARGUMENT 















i 1 1 r— 1 — i Hi 

STATEMENT INCREMENT PSX +1 
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The Label 



The label is a name for the statement. Labels are optional, but you 
must give a name to a statement if you refer to it in another state- 
ment. The commands in WPL that refer to another statement are go 
and Subroutine Call (SR). 

You may also give any statement a name in order to help you 
remember what the statement does. This is known as internal docu- 
mentation— information about a program that is contained in the 
program itself. (Another way to document your program is to include 
comment statements. You will learn how to write comments later in 
this chapter.) 

Here are the rules for writing a label: 

• It must begin in the leftmost position of the line (that is, at Tab 
position on your screen). 

• It may contain any character except the space, including upper- 
and lowercase letters. 

• It may beany length. 

• It must be followed by at least one space. 

When you refer to a label in a WPL statement, you must spell it 
exactly the way you did when you wrote the label. The following 
list contains three different labels: 

MYLABEL 
my label 
MyLabel 

Here's what a label (getfile) looks like as part of a statement in 
a WPL program: 

GETFILE L .dl' filename 
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The Command 



The command is like a verb; it's the part of a statement that tells 
the computer what to do. Most commands contain two parts: the 
command name (like [r]ind or do) and an argument (described in 
the next section). Some commands do not take arguments. Here 
are the rules for writing a command: 

• Leave one or more spaces before the command, whether or not it 
is preceded by a label. 

• If the command is an Apple Writer command, type the command 
name by itself, without using the (control) key; for instance, type 
[L]oad or [s]ave as l or 5. 

• If the command is a WPL command like np or DO, place the 
letter p immediately before the command name: pnp orPDO. (The 
p stands for the Apple Writer [p]rint/Program command.) 



The Argument 

Argument is a mathematical term that programmers use. The argu- 
ment is the part of a command that gives additional information 
about it. In other words, it's a modifier that tells Apple Writer precisely 
how to execute the command. Some commands (like [E]nd) work all 
by themselves without an argument. Others have an argument that 
consists of one, two, or more parts. As you are introduced to each 
new command in this manual, you'll be told exactly how to write the 
argument if the command takes one. 

The argument is the last part of a statement, and it is always fol- 
lowed by (return) . This means that the next statement in the 
program always starts on a new line. In the following statement, 
.dl'autoletter is the argument: 

PDO .dl^autoletter 
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Let's begin with a question of style. Some programming languages 
require you to write certain parts of a statement in particular posi- 
tions on the line. (These positions are often called columns because 
they originally referred to the columns of a keypunch card.) WPL, 
on the other hand, is quite flexible in its format. Nevertheless you 
may find that your program is a lot easier to read and work with if 
you follow a set pattern in writing statements. Here is the one 
we recommend: 

• Decide how long your longest label will be. Then begin every 
command two positions beyond that point, whether or not the 
command has a label. That way the commands will be lined up 
and easy to read. 

• When spaces between the command name and the argument are 
optional, use them. Apple Writer won't care, and you'll be able to 
read your program more easily. 

• If you line up the commands as we suggest, a statement will use 
the same number of characters in its label area whether it contains 
a label or just spaces because spaces are counted as characters. 
Therefore use labels liberally to remind you what the statements 
do. In the lordfile program below, the first statement takes no 
more room than the last statement. 

LORDFILE L .Dl' LETTER 
REPLRCE F/1981/1983/R 
PRINT PNP 

S .Dl^LETTER 

• If your program is long, you'll save room by keeping your 
labels short. 



Writing an Apple Writer Command 

Here are the rules for writing an Apple Writer command in a 
WPL program: 

• Type the one-letter command name without pressing the 
(control i key. If you want [F]ind, type f, if you want [Glossary, 
type g, and soon. 

• For file commands ([L]oad, [s]ave), spaces between the command 
name and the argument are optional. 
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• For all other commands, spaces between the command name 
and the argument are not allowed. 

Here are the rules for writing the argument of an Apple Writer 
command in a WPL program: 

• Type the argument exactly the way you would type it if you were 
using the command as an immediate command. That is, if you 
must press control or return i when you enter the argument in 
Apple Writer, press ( co ntrol or return when you enter the 
argument in your WPL program, i contr ol; should always be pre- 
ceded and followed by [v]. 



• Always end the statement with Creturnj . if the statement has no 
argument, press (return) after the command name. If there's an 
argument, press (retur n) at the end of the argument. 

• If, when you type the command in Apple Writer, you need to press 
( return] twice (for instance, to exit from the DOS Command 
Menu) then you must also press return twice when you use the 
command in a WPL program. However, in the WPL program you 
must put one or more spaces between the two return ' s . This is 
because the second f return ) cannot be in the leftmost position 
of the line. If it were in the leftmost postion, it would look like 

a label and be ignored. This in turn would mean that the (return) 
at the end of the following line would be used to exit from the 
menu and the command on that line would be ignored. 

Now let's look at three examples of Apple Writer commands written 
as program statements. Each statement begins on a new line 
because the preceding statement ends with i '.return . 

Apple Writer Command Description 

1. b Move cursor to beginning of file. 

2. ny Clear memory. 

3. f June/July Find and replace text. 



Y? 
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Example 1. b 

[b] is an Apple Writer command that doesn't need an argument. It 
Example: move cursor to beginning of file moves the cursor to the beginning of the document in the memory 

buffer, and it sets the direction to > . In a WPL program, you use this 
command if, for example, you want to search for a marker from the 
beginning of a document to the end. For instance 

L . dl' budget . annual Load file. 

B Move cursor. 

F/1982/1983/fl Find, replace all dates. 

This little program loads a file called budget . annual into the text 
buffer from the disk in drive 1 . It moves the cursor to the beginning 
of the document in memory and then searches through the docu- 
ment, replacing every occurrence of 1982 with 1983. 

Now that you know the syntax rules for Apple Writer commands 
in a WPL program, you should be able to read this sample program 
without difficulty. If you're having trouble remembering what the 
Apple Writer commands do, please look them up in your Apple 
Writer manual right now. 

Even if you're feeling pretty comfortable with Apple Writer, you may 
find it helpful to review all the features of each command before you 
begin programming. That's because some features are especially 
useful when used in a program, and you might have missed their sig- 
nificance the first time around. 

Example 2: NY 

[N]ew is an Apple Writer command that requires an argument. 
Example: clear memory The command clears memory. When you press [n ] , Apple Writer 

responds by asking you if you really want to erase memory, and you 
may answer either y or n. Because you are prompted for an answer 
when you use [n] as an immediate command, you must respond as 
if you were prompted when you issue this command in a WPL pro- 
gram. Remember, WPL is like a player piano— the same notes are 
played whether or not the pianist is at the keyboard. 

You want your program to answer yes, of course. If you didn't, you 
wouldn't have written a [N]ew statement in the first place. So type 
the response, which is this command's argument, just the way you 
would if you wanted the command to be executed immediately. 
Notice that there aren't any spaces between the n and the v. You 
wouldn't have typed a space at the keyboard, so Apple Writer doesn't 
expect you to put one in your program. 
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Example 3: F/June/July 

Y? 

[F] is an Apple Writer command whose argument has more than 
one part. You can use this command to find text (that is, position the 
Example: replace a word cursor), or to find and replace the next occurrence of the text (which 

is what this example does), or to find and replace all occurrences 
automatically. 

The [F]ind statement requires two lines in your WPL program. That's 
because you would have to press return i after typing /June/July 
if you were entering the [F]ind command at the keyboard for imme- 
diate execution. If you want to see for yourself, type some text 
containing the word June and then do the following: 

Press [6] (Move cursor to start.) 

Press [f] (Find/replace command.) 

Type /June/July (Replace June with July.) 

Nothing happened, right? That's because you haven't pressed 
C return) yet. Do that right now, and you'll see the next prompt: 

[F] ind: RETURN = Proceed Y = Replace 

Type v and the replacement will be made. You'll also get the final 
prompt, without having to press (return) ; 

[ F ] ind: RETURN - Proceed 

Now type 

? 

The prompt disappears and the cursor is positioned after the text 
that was replaced. (The question mark is explained below.) 

If you look at the statement that contains this Apple Writer com- 
mand, you'll see that the statement does exactly what you did at the 
keyboard. Here it is again: 

F/June/ July/ 
Y? 

Where you had to press ( return ) , the statement contains a ( return ) 
and continues on the next line. Where you didn't press (return) 
after the v, the statement continues on the same line. That's the way 
all Apple Writer commands are written in WPL— just the way they're 
entered "live at the keyboard." 
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It's probably all clear to you now except for that question mark. 
What in the world is that? You should be able to see from the syntax 
you've learned that it's a response to the final prompt: 

[F ] ind: RETURN = Proceed 

What's confusing is that you're used to responding to that prompt 
with a space if you don't want to proceed. However, if you go back 
to your Apple Writer manual, you'll see that any character except 
( retur n i will have the same effect as a space. 

Since a space doesn't print, you can't see whether it's there or not. 

Your WPL program can read it, but you can't. Therefore most WPL 
How to exit from the [f] ind command in programmers use the question mark by convention to exit from the 
aprogram [F]ind command. 

Writing a WPL Command 

Here are the rules for writing a WPL command in a program: 

• Precede the 2-letter command name with the letter p. For instance, 
np becomes pnp, cp becomes pcp, and so on. 

• For a few commands— Assign String, Input, and Print— spaces 
between the command name and the argument are considered 
to be part of the argument. 

• For all other WPL commands, spaces between the command 
name and the argument are optional and may be used to make 
your program more readable. 

• Always end the statement with [return] . if the statement has no 
argument, press t return'; after the command name. If there's an 
argument, press (return) a t the end of the argument. 

Here are the WPL commands you learned in the Apple Writer 
manual, first as they are written in WPL and then as they are entered 
as immediate commands: 

In a Program From the Keyboard 

PDO filename Press [P] 

Type do .d2/ filename 

pnp Press [p] 

Type np 

pcp Press [p] 

Type CP 
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The rest of this manual will teach you how to write programs and 
how to use the 14 other WPL commands. 



Writing Comments 

Comments are statements that annotate your program. The format 
of a comment statement is 

{label} space(s) P space(s) text of comment 

Braces (| |) mean that the label is an optional part of the com- 
ment statement. 

The comment format is a useful convention. If, while executing 
a program, Apple Writer finds a command it doesn't recognize, it 
throws it away— that is, the unrecognized command is ignored. 
Apple Writer interprets the comment format as an unrecognized 
WPL command because the first character after the p is a space. 

Comments help you remember how You cannot believe how easy it is to forget how your program works 
your program works. or even (-, w to read it until it happens to you. Therefore when you 

write a program it's important to document it by inserting comments 
that explain the design of the program. Here are some other docu- 
mentation techniques you might want to consider: 

• Keep a list of all the files on each disk, with a one-line statement 
of the nature of each file. 

Note that you can write ail your docu- • Write a paragraph about each program you write, with an 
mentation with Apple Writer! explanation of what the program does and how to run it. 

• Make a master list of all programs and files that work together to 
accomplish a particular job. 
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Here is an example of a commented program called star. The first 
statement is a comment. Its label is the program name and the 
comment itself is the program description. The convention of 
labeling the first statement with the program name is used through- 
out this manual. 



STAR p THIS PROGRAM FILLS MEMORY WITH STARS (comment) 
ny 

p INSERT A STAR INTO MEMORY (comment) 
Example: filling memory with stars f/s*/ 

loop e 

p load more stars (comment) 

Ltt 

pgo loop 



You know all the commands in this program except for the very last, 
pgo loop, which says, "Go to the statement labeled loop and begin 
executing instructions." You'll learn more about the Go command in 
the next chapter. 



By the way: The star program illustrates a handy way to insert text into 
the document in memory. Just use the [r] ind commmand to find "nothing" 
and replace it with text, like this: 

(The WPL equivalent of "nothing" is two delimiters with nothing 
in between.) 

The text is inserted at the current cursor position. You can also delete text 
by replacing it with nothing, like this: 



Here's a chance for you to practice editing and running a WPL 
program. Clear memory and type the sample program in with Apple 
Writer. Notice that Apple Writer doesn't do anything except edit 
text— it doesn't try to execute any of the commands because you 
haven't entered them in immediate mode. 

When you're finished typing, save the program and run it. Watch the 
screen fill up with stars and see the length value (Len:) on the Data 
Line increase. Soon the computer will beep and the cursor will 
begin flashing again. That means the program has filled all of 
memory and has halted. 
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Now clear memory and load the program so you can edit it. Change 
it so that it places *a$ in memory. Save the new version and run it. 
You can stop the execution of the program at any time by pressing 
( escape) . (Look in Appendix E to see if you modified the STAR 
program correctly. Appendix E contains the answers to all of the 
programming questions in this manual.) 

Try "playing computer" by reading the program and writing down 
the results of each statement so that you can see for yourself why 
the program works the way it does. See if you can change the pro- 
gram so it fills memory faster or makes a more interesting pattern on 
the screen. 

When you're ready to learn some new WPL commands, go on to the 
next chapter. 
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In this chapter you will learn 

• how to end a WPL program. 

• how to perform repetitive functions in a WPL program. (You saw 
an example of this in Chapter 2, when you ran the star program 
which fills memory with stars.) 



The four ways to stop a program 



Ending a WPL Program 

You already know one way to stop a running WPL program: press 
( escape j and it will immediately stop. That's a little like stopping a car 
by driving it into a brick wall. There are two ways that you can pro- 
gram a graceful ending: by executing the last statement or by using 
the Quit command. Apple Writer also stops your program when it 
finds an error in it. 

Executing the Last Statement 

In a simple WPL program, the statements are executed in sequence 
until the last statement is encountered. When there are no more 
statements to execute, the program stops and Apple Writer returns 
you to its edit function. The MEMOPRT program at the beginning of 
Chapter 1 is an example of halting by executing the last statement. 
Here's another example, the append program: 



Example: appending files 



(For a more general version, see 
appendi' in Chapter 5.) 



APPEND P THIS PROGRAM MAKES THREE FILES INTO ONE 

NY 

L . D2/ JANUARY 
L . D2-'FEBRUARY 
L . D2/MARCH 
S . Dl 'QUARTERl 
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The append program doesn't need a special command to tell Apple 
Writer when it's done. More complex programs, however, may be 
written so that the last statement in the program isn't necessarily the 
last one to be executed. In that case, the Quit command is used. 

The Quit Command 

The format of the Quit command is 

PUT 

When Apple Writer encounters the Quit command in the course of 
running a WPL program, it stops the program and puts you back in 
the Apple Writer editor. Whatever was in the text buffer while the 
program was running is still there. 

You may use the Quit command more than once in a program. The 
message program, below, contains two Quit statements. 

Example: Printing a daily message MESSAGE L . Dl-'MSG . OA ILY/JUNE 07' JUNE 06 - N 

PGO PPINT 
PQT 

PRINT PNP 
PQT 

The first Quit statement causes the program to stop only if the 
june 07 marker is not found. (We'll tell you more about why some 
commands work only under certain conditions in the section "Con- 
ditional Execution" in Chapter 5.) The second Quit statement causes 
the program to stop after printing the text between the markers. 



Interruption Due to Error 

When you run a WPL program, Apple Writer sometimes finds 
a condition that keeps it from proceeding further. For instance, you 
may have told it that a certain file is on your disk, but Apple Writer 
can't find the file because you misspelled the name in your program 
When Apple Writer recognizes an error condition, it says in effect, 
"I give up. I can't continue to run this program. Here's the problem 
I found, displayed on the screen." 
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Appendix D lists and explains the five WPL error conditions that can 
cause Apple Writer to stop running a program. If the error message 
displayed on the screen is not covered in Appendix D, it's a SOS 
message and you will find an explanation of it in the Apple Writer 
manual. (Errors associated with files are usually SOS errors.) Please 
look at Appendix D now to familiarize yourself with the format of the 
error messages and the types of errors that can occur. You may not 
understand these messages right now, but you will shortly. 

If your program stops with an error message, look up the message 
in Appendix D to find an explanation of the message and some 
suggestions as to what might have caused the error. When you find 
the problem, load and edit your program, save the corrected version, 
and run the program again. 

Program Loops 

Program loops are a means of doing repetitive tasks. If you want 
How to do things over and over again a certain function in your program to be performed over and over 

again, you don't want to have to write out a complete set of instruc- 
tions for each repetition. In WPL there's a way to say, "Go back and 
do that again." In fact, the command is called go. 

Here's how program loops work. Let's say that there's a circular 
track near a jogger's house. Every day the jogger walks to the track, 
runs around it five times, and then walks to the office. Figure 3-1 
shows what the jogger's path looks like: 



Figure 3-1. A Path Containing a Loop 
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Figure 3-2. Program Logic of the 
Jogger's Path 




The loop in the path is the part that is repeated. It's called a loop 
because the end joins the beginning to make a circle. A program, on 
the other hand, is a (more or less) straight path. It has a beginning, 
a middle, and an end. But it may contain any number of loops. If 
you were to write a program to describe the jogger's path, its logic 
would look like the drawing in Figure 3-2. 

The Go Command 

The Go command makes program loops possible in WPL. The for- 
mat of the command is 

PGQ statement label 

Normally Apple Writer executes WPL statements consecutively. The 
Go command, however, causes execution to continue at the state- 
ment whose label is named in the Go command. For example 



loopl 



jif condition 1 skip next statement! 

pgo loopl 



loop2 



{if condition 2 skip next statement} 

pgo loop.2 



This example shows two loops in a program, equivalent to having 
our jogger run around the track a few times ( i oopi ) and then run 
around the office building a few times ( l oop2). The first loop is exe- 
cuted until condition 1 occurs; then the Go statement is skipped 
and the program proceeds to loop 2. The second loop is executed 
until condition 2 occurs. Chapter 5 tells you how to define conditions. 
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It is also possible to nest loops so that one falls inside another: 

A nest of loops loop:-; ... 

loop-4 . . . 

[if condition 4 skip next statement! 

pgo loop -4 

{if condition 3 skip next statement; 

pgo loop 3 



Exiting From a Loop 

A never-ending loop is not usually a good idea, for a jogger or for 
a program. The STAR program in Chapter 2 contained an endless 
loop, but it was the kind that Apple Writer would eventually find out 
about. Sometimes Apple Writer doesn't know or care if your loop 
goes on forever. If you happen to be printing in the loop, you can 
chew up vast forests worth of paper before you discover the problem. 

There are three ways of exiting from a loop: 

• You can use the Go command to go (or branch) to a statement 
outside the loop. 

• You can use the Quit command to end the program. 

• You can take advantage of conditional execution, a feature of 
WPL in which certain commands may cause the next statement 
in the program to be bypassed. Chapter 5 tells you how to use 
conditional execution. 
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utput 



This chapter covers WPL's facilities for 

• writing files, 

• sending messages to the screen, 

• receiving input from the keyboard, 

• and printing text. 

Saving a File From a WPL Program 

You can write a program that creates a file or modifies an existing 
file and saves the results on a disk. You have already seen an exam- 
ple of this. The append program in Chapter 3 created a quarterly file 
by loading three monthly files into the text buffer and then issuing 
a [s]ave command. This program saved the entire document in the 
qufiRTERi file. 

Refer to the Apple Writer manual for You can also use the special features of the Apple Writer [s]ave 
more ways to save and load files. command to save part of a document in a new file or to add part or 

all of a document to an existing file. A WPL program that saves part 

of a document in a new file is 

sauepart L .d2'oldfile 
b 

f/ f i rstuord/ 

s .d2/newf ile! lastuiord* 

A WPL program that adds a document to the end of an existing file is 

addon L . dl ''neuda t a 

s . dl/oldf i 1 e + 
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Printing From a WPL Program 

When you learned Apple Writer, you learned how to use the np 
(New Print) and CP (Continue Print) WPL commands as immediate 
commands. You also saw these commands used in the memoprt 
program in Chapter 1 of this manual. In Chapter 5, you will discover 
how to create a menu program that uses these commands to print 
any number of files. For a summary of the New Print and Continue 
Print commands, see Appendix C. 

Sending Output to the Screen 

One of the most useful enhancements WPL makes to Apple Writer is 
the capability of sending and receiving screen messages, allowing 
you to interact with a running WPL program. You have already used 
programs that do this: the Help screens in Apple Writer are created 
using WPL programs to display menus and receive your input. This 
chapter introduces you to various screen output commands 
and techniques. 



The Print Command 

The Print command displays text on the screen. You can use it to 
display up to 1 28 characters of text, but we recommend that you 
limit your text to that which will fit on one line of your display. 

The format of the Print command is 

PPR text 

Any spaces between the command and the first printable character 
will be treated as part of the text and placed on the screen. For exam- 
ple, the following command displays a centered heading on an 
80-column display: 

PPR DAPPLED SAPLINGS TOPPLED 

The text portion of the Print command may contain any combination 
of keyboard characters. A blank line is displayed if the command is 
entered without an argument: 

PPR 
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The Input Command 

The format of the Input command is 



PIN text 



Additional features of the Input com- 
mand are described in Chapter 5. 



This command displays a line of output on your screen, just as the 
Print command does. But Input also causes the program to stop 
and wait for you to press ( return) . Here's an example: 



Example: getting your program to stop 
temporarily. 



HALT PND 

PPR [G] 

PPR ===== I riser t special forms in pr inter 
PIN Then press RETURN 



In the first line, pnd, the No Display command, allocates the entire 
screen to messages rather than to text. The first Print command 
rings the bell to get the user's attention, ([g] causes the bell to ring.) 
The second Print command displays a message line on the screen. 
The Input command displays another message line and causes the 
program to stop and wait. When the user signals by pressing ( return 
that the proper paper has been loaded, the program continues 
processing. 



Try the halt routine now to see how it works. 



• Type the four program statements using Apple Writer. You must 
press [v] before and after [G] (to enter and leave Control Charac- 
ter Insertion mode). See the section "Clearing the Screen," below, 
for more about [V]. 

• Save the program in a file— do not save it on the MASTER disk. 

• Run it using the Do command. 

You'll see the two messages displayed on the screen. Now press 
(return ) and watch the messages disappear. (The screen now 
contains whatever was there before you ran the halt program. 
Whenever a WPL program ends, the text buffer display is restored 
to the screen.) 
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Here's another example of a program that uses the Print and Input 
commands. The section shown below displays a logo for the pro- 
gram LETTER. 

Example: logo display LETTER PND 

PPR [S ] 

PPR 

PPR 

PPR ************************************************ 

PPR * 

PPR* WIDGET INDUSTRIES, INC. * 

PPR* For m Let ter Generator * 

PPR * * 

ppR ************************************************* 

PPR 

P I N P r ess retu r n t o beg in... 



The statement ppr [\] (which clears the screen) is explained below. 

The Input command, in addition to stopping and starting a WPL 
program, can be used to receive information from the user and 
deliver it to the program during execution. You will learn how to do 
this in Chapter 5. 

Controlling the Screen Display 

Apple Writer usually reserves only one line on the screen for output 
messages from a program. That's because the rest of the screen is 
kept for display of the document in memory. But you can control 
the use of the screen by using the WPL commands ND (No Display) 
and yd (Yes Display) to turn the document display off and on. 



Your program will run up to five times The No Display Command 

faster when the document in memory is 

not displayed. The ND ( No Display) command turns off the text buffer display so 

that the entire screen may be used for message output. No Display 
is usually the first command in a WPL program. 

The format of the command, which does not take an argument, is 

PND 
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If you issue a series of Print commands in your program and forget 
to turn off the text display with no, the output messages will be 
displayed one at a time in the one-line space provided for them... at 
computer speed. All you'll see is a fast flicker. Therefore if you want 
to display several lines of information, such as a menu, you must 
use the No Display command. You must also put an Input command 
( i n) at the end of the lines of information so that they continue to be 
displayed until the user presses f return ), 



The Yes Display Command 

The yd (Yes Display) command turns the text buffer display back on 
so that you can display the document your WPL program is working 
on. This can be helpful while you're developing a program because it 
lets you see the effect the program statements are having on the text. 

Document display is the state that Apple Writer is in unless you tell it 
otherwise. The format of the command, which does not take an 
argument, is 

PYD 



Clearing the Screen 

Before you load a file, you normally clear memory. Similarly, before 
sending messages from a program to the screen, it is customary to 
erase the screen. 

The Print command that clears the screen is shown in this manual 
as follows: 

PPR [ \ ] 



Inserting control characters in a WPL 
program 



This means "Enter the command by typing ppr and then pressing [v] 
[\] [v]." The first [v] tells Apple Writer to enter Control Character 
Insertion mode so that [ \] or any other control character is entered 
as text. (The [\] is a clear screen character.) The second [v] causes 
Apple Writer to exit from Control Character Insertion mode and 
enter Text mode again. When the program is run, Apple Writer 
executes the statement ppr [\ ] by clearing the screen. 
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This chapter explains the terms siring and variable. It shows you 
how to use string variables to 

• create and manipulate strings of text; 

• compare a string to a constant or to another string; 

• use strings in place of constants in Apple Writer commands; 

• modify a program at execution time by using string variables; 

• write a menu program. 

H^HHHH Introduction to String Variables 

In this section you will learn what a string variable is and why it is 
such a powerful programming tool. 

What Is a String? 

a string is text. Simply stated, a string is text. Each word in this sentence may be 

thought of as a string— a sequence of characters strung together. In 
WPL, a string may contain up to 64 letters, numbers, and any special 
characters you can enter from your keyboard, including control 
characters and space characters. Each line below is an example of 
a valid string: 

ft 

. dl/ f i lename 

*************************************** 
[G] 

tt$a!*& 

Cupertino, ca 95014 
10 

Fourscore and seven years ago 
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What Is a Constant? 



A constant is a string that always has the same value. Its value does 
not change while the program is running. All of the strings shown in 
the previous section are constants. 



What Is a Variable? 

In algebra, a variable is a letter or symbol that represents an 
unknown number. Sometimes the letter represents a specific num- 
ber, as in the expression 

x = 10 + 2 

Other times the letter may represent an infinite number of possibil- 
ities, as in the expression 

x = 10 + y 

In this expression, x is known only when we know what y is. 

Both of these uses of variables are found in WPL. That is, a variable 
may represent a specific value such as "YES" or "10", or it may 
represent a vast number of possibilities such as "any file name" or 
"any number from 1 to 1 ,000". Your program can control how a given 
variable is used— more about this in the next section. 

There are two kinds of variables in WPL: string variables and numeric 
string variables versus numeric variables variables. String variables, which represent text, are described in this 

chapter. Numeric variables, which represent numbers, are described 
in Chapter 6. The difference between numbers in string variables 
and numbers in numeric variables is that you can do arithmetic only 
with a numeric variable. 

String Variables in WPL 

WPL uses four symbols for string variables: $R, $B, $c, and $D. 
These may be entered in either upper- or lowercase. $fi and $a are 
the same variable. Each variable may be used over and over again 
to represent different values of text during the course of a program. 
Whenever a variable name appears in a program, Apple Writer sub- 
stitutes the current value of the variable. 
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You can think of a variable as a bucket that holds whatever you put 
in it. (See Figure 5-1 .) The contents of the bucket will be there until 
you put something new in the bucket. When you do, the old contents 
are automatically emptied out before the new contents are put in. 

Your program can decide whether a given variable may contain 
any value at all or whether it must contain a specific value or set of 
values. In the APPEND2 program, which appears later in this chapter, 
all of the variables may contain any value— the program doesn't 
check them. In the choice program (also later in this chapter), the 
$a variable must contain the answer "yes" or "no"; otherwise 
the program asks the question again. 



Figure 5-1. A String Variable Bucket 




A string variable may be used in any Apple Writer or WPL command 
instead of text. Here are some examples of string variables used 
in statements: 

1. ppr The new f i le for month $a is $b. 

2. L $D -$H 

3. fv$c/$b/a 

In example 1 , the $a variable represents the name of a month and 
the $b variable represents a filename. In example 2, the $h variable 
represents a filename and the $d variable represents a drive designa- 
tion. In example 3, the $c variable represents the string to be replaced 
and the sb variable represents the replacement string. 
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The WPL program that contains these statements assigns each 
variable its value by means of the Input command, the Assign String 
command, or the Load String command. These commands are de- 
scribed in the next section. Here is how the three statements might 
look if Apple Writer replaced the variable names with the current 
values of the variables: 

1. ppr The fteu file for month JULY is JUL23 

2. L .Dl'STQCK 

3. rVnuts/bql ts/a 

Setting a String Variable 

A string variable keeps its value until its bucket is filled with a 
different value. Filling the bucket is also called setting the variable. 
You may set a string variable by 

• typing its value while the program is running (in response to the 
Input command); 

• assigning a specific value to it in your program (with the Assign 
String command); 

• loading text from a file into the variable (with the Load String 
command). 

Additional Features of the INPUT Command 

The format you learned for the Input command is 

PIN text 

In this format, te> t is displayed and the program halts until you 
press ( return ) . (Remember that the string includes the space before 
text.) The expanded format of the Input command is 

PIN text = $fi 

where $ft may be any string variable. In the expanded format, t e t 
is displayed but = $r is not displayed. When the program halts, what- 
ever you type before pressing (return) , up to 64 characters, will be 
stored in $h (that is, in any string variable named in the Input 
statement). 
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You can try out a simple program right now that uses the two formats 
of the Input command. Just type in the following five-line program, 
[s]ave it in a file, and execute it. 

Example: pick a number pick pnd 

PP r [ * ] 

pin Pick a number from one to t en . then press RETURN . = $A 

pin The number you picked is $R; press RETURN . 

pqt 

Whatever you type is put in the $h bucket by the first Input state- 
ment and displayed by the second Input statement. You can type 

three Or 3 Or ant idisestabl ishmentar lanisffl and the program 

echoes it. Later in this chapter you'll learn how to use the Compare 
Strings command to find out what was typed and take different paths 
within the program depending on what's in the bucket. 

Note: Variables give you a way to generalize a program. For instance, 
the APPEND program in Chapter 3 consolidates 3 specific input files 
(January, February, and march) into a specific output file. By substituting 
string variables for the file names, you can make a program that works 
with any files you specify at execution time: 

APPEND2 P THIS PGM MAKES ANY THREE FILES INTO ONE 
NY 

PIN WHAT'S THE FIRST FILE? = $a 
L $a 

PIN WHAT'S THE 2ND FILE? = $b 
L $b 

PIN WHAT'S THE 3RD FILE? = $c 
L $c 

PIN WHAT'S THE OUTPUT FILE? = $d 
S $d 

All of the Apple Writer menus are written in WPL using the Input 
command. By the end of this chapter you'll be able to write your own 
menu program. 
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You can fill a string variable bucket from outside the program by 
using the Input command or from inside the program by using the 
Assign String command. The Assign String command allows your 
program to fill any string variable with text. 

The format of the Assign String command is 

PAS text = $H 

where $a represents any string variable and t e t is the value to be 
assigned to the string variable. The spaces before and after the text 
are also assigned to the string variable. The variable to the right of 
the equals sign represents the bucket to be filled. The following are 
legitimate Assign String statements: 

pas Thank you for your let ter dated = $H 
PAS International Industries Inc. = $C 
pas .02/ = $d 

Note: Variables may appear on both sides of the equals sign so that you 
can give a string variable the value of any string variable(s) plus text. We'll 
tell you more about this in the next section. 



Concatenation 

Combining two or more strings is called concatenation. When 
concatenating strings, the total length of the new string (the variable 
on the right of the equals sign) may not be more than 64 characters. 
Three examples of concatenation are shown below. 

In the first example, two text strings are concatenated with a string 
Example: putting brackets around a string variable ($a). The first text string is a blank space and a left bracket 

( [ ) and the second text string is a right bracket ( ] ). The result is 
placed in the same string variable; the previous contents of $a 
are destroyed. 

pas [$a] = $a 

If the value of fa is apple before the Assign String statement is exe- 
cuted, then the value of $a after execution is [ apple ] . The space 
between the command and the left bracket is part of the argument. 



i 
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In the second example, three string variables ($d, $c, and $h) are 
concatenated and placed in $b: 

PflS$fl$D$C = $B 

If the value of %f\ is . di and the value of $d is wpl . and the value of $c 
is memoprt then the value of $b after execution is . di/wpl . memoprt. 

In the third example, text including space characters is concatenated 
with two string variables; $b represents a first name, $c represents 
a last name, and $a contains the result after execution: 

pas Mr . $b $c = $a 

If the value of $b is John and the value of %c is Doe, then after 
execution of this Assign String statement, $a will contain the value 
Mr . John Doe (including the space between pas and Mr . ). 

Concatenation is a useful way to store the contents of two or more 
buckets in a single bucket. For instance, here's a routine that asks 
for three pieces of information and saves them in a single variable 
for use later in the program: 

Example: collecting parts of an address pnd 

pin What ' s your ci ty? - $a 

pin What 's your state? = $b 

pin What ' s your zip code? = $c 
pas $a , $b $c = $a 
ppr Your rnai 1 ui 1 1 be sent to$a . 



Notice: There is a space between the Assign String command and $a in 
the second-to-last statement; this space is actually part of the argument 
of the Assign String command. When text is substituted for fa in the last 
statement, it will begin with a space. 

That's why there's no space between to and $a in the last statement. If 
you had a space in the text and a space in the variable, you would get 
two spaces between t □ and the address when the substitution was made. 
Here is another way to write the last two statements of the routine: 

pas$a . $b $c = $a 

ppr Your mai i ui 1 1 be sent to $a . 

After this routine has been executed, $b still contains the state and 
so still contains the zip code, but you can now reuse $b and $c by fil- 
ling them with new values since $a contains the city, state, and zip 
code formatted with commas and spaces. 



Example: putting strings together 



Example: adding strings that contain 
spaces 
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The Load String Command 



Load String lets you set a string variable from a file. (Input lets you 
set a string variable from the keyboard. Assign String lets you set 
a string variable from within the program.) The format of the Load 
String command is 

PLS .dZ'/f i 1 enamels tart lend! AN = $h 

where s t a r t identifies the beginning of the string to be loaded and 
end identifies the end of the string to be loaded. $h represents the 
string variable being loaded. The Load String command has no 
effect on the document in memory. 

Load String works exactly like [L]oad except that [L]oad places text 
in the text buffer and Load String places up to 64 characters of text 
in a string variable. As in [L]oad, you may specify A or N or both. A 
means load all occurrences of the string, n means don't include the 
start and end markers in the string variable. 

Let's look at an example of how this command works. You might 
want to type in the small program and data file so you can try this 
out for yourself. The data file, NAMES, looks like this: 

Brown , Mary 
Jones , Lee 
Kitchen, Chris 
Sunn, David 

The program prompts for a last name, uses the Load String 
command to get the first name, and displays first and last name 
on the screen: 

Example: finding names in a file GETNAME PND 

PIN Enter last name = $a 

PLS .d2/NAMES<$a, < ><n = $b 
PIN fa ' s f i rst name is $b 
PQT 

As you can see, the Load String command is handy for looking up 
values in tables and lists. Notice the use of special delimiter charac- 
ters. The first marker in the Load String statement is a concatenation 
of a string variable and text (the comma). The second marker is the 
return character (>). 
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If the first marker in the Load String command is not found, the next 
statement in the program is skipped. This is called conditional 
execution— it's one of WPL's most powerful features; you will learn 
all about it in the next section of this chapter. 



Conditional Execution 

There are times when you can't write a precise program command 
because you don't know exactly what the conditions will be when 
it's executed. For example, you may want to tell Apple Writer to put 
a message on the screen only if the previous [F]ind found what it 
was looking for. Since you can't know in advance whether or not the 
text will be found, you have to provide for both possibilities in your 
program. If the text is found, Apple Writer executes the next state- 
ment; if the text isn't found, the next statement is skipped. This is 
called conditional execution because a statement is either executed 
or skipped depending on the outcome of the previous statement. 
We refer to the condition that causes the next statement to be 
skipped as the unsuccessful outcome. 



Figure 5-2. Conditional Execution 





Figure 5-2 shows the logic behind conditional execution. The same 
picture can be drawn with words: 

FIND SOME TEXT 
DISPLAY THE TEXT 
GO TO NEXT SEARCH 

The second statement, DISPLAY THE TEXT, is executed only if the 
text is found. The third statement. GO TO NEXT SEARCH, is always 
executed. If the text is not found, the second statement is skipped 
and Apple Writer goes directly to the third statement. 
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Conditional execution applies to both WPL commands and Apple 
Writer commands. As you learn the WPL commands, you will be 
told which ones cause conditional execution. (You learned earlier in 
this chapter that the Load String command causes conditional 
execution.) 

Here are the Apple Writer commands that cause conditional execu- 
tion when written in a WPL program: 

Command Next statement skipped if... 

[F]ind Text not found 

[i_]oad with markers First marker not found 

Comparing Strings 

In the getname program earlier in this chapter, a variable is used as 
a marker in a Load String command. In this particular case, the pro- 
gram doesn't have to know the current value of the variable. Some- 
times, however, a program needs to make a choice that depends on 
the value of the variable. In a menu program, for instance, the 
keyboard input determines which menu item is selected. The 
Compare Strings command tests a variable to see if it contains 
a particular string— for example, a particular menu selection. 



The Compare Strings Command 

The Compare Strings command determines whether two strings are 
equal, and causes conditional execution. If the strings are equal, the 
next statement is executed. If the strings are not equal, the next 
statement is skipped. 

By the Way: Two strings are equal if they are the same length and if both 
strings contain the same characters in the same order. The following 
strings are equal: 

BA135C = BA135C 

The following strings are not equal: 

BA135C not = BA135CD 

BR13 not = B13R 

Bfi 135C not = BA135C 
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The format of the Compare Strings command is 



PCS /stringl/string?/ 

s t ringl and string2 may consist of text, one or more string varia- 
bles, or a combination of these. 

The delimiters for the Compare Strings command are similar to the 
delimiters for the [F]ind command: the first non-space character 
typed after the command is the delimiter. 

The following are valid Compare Strings statements: 

pcs/$a/$b/ 

PCS .YES.SC. 

pes /$dSb/July 1983/ 

PCS ■ Ms. $R!$B! 

The following routine demonstrates the use of string variables and 
conditional execution in comparing strings: 



choice ppr Do you want to print another file? 

pin Enter YES or NO; then press RETURN. = $a 
pes /$a/YES/ 
pgo print 
pes /$a/NOV 
pgo qu i t 

ppr You didn' t answer the quest ion ! 
pgo choice 

After each Compare Strings command, the next statement will be 
executed only if the comparison is equal. Because the next state- 
ment in each case is a Go command, the statements after the Go 
command will be executed only if the strings are not equal. It is also 
possible to have two Go commands in a row; compare the following 
routine to the routine above: 



Example: comparing YES and mo 



pnd 



Example: print or quit 



pin To print another file type Y , then press RETURN . = $a 
pes /$a/Y/ 
pgo print 
pgo qui t 
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In this version, any response other than v will cause the program to 
execute the quit routine. "Y" and "y" are not the same! How would 
you rewrite this routine so that the user could type either an upper- 
case or lowercase response? (See Appendix E for the answer.) 



A Sample Menu Program 

It's often helpful to print a document on the screen in order to 
review it before it goes on paper. In order to print on the screen, you 
must change the print destination setting using the Apple Writer 
[p]rint/Program command. The menu program determines whether 
you want to print on the screen or on the printer; it then changes the 
print destination setting automatically and prints the file. 



Example: a menu program 



menu 



pnd 





ppr [ S ] 




ppr PRINT OPTIONS MENU: 




ppr 




ppr (1 ) Screen 




ppr (2) Printer 




ppr (3) Quit 




ppr 


select 


pin Select 1 , 2 , or 3: 




pes /$a/3/ 




pgo qu i t 




pes /$a/2/ 




pgo printer 




pes /$a/l/ 




pgo screen 




pgo select 


screen 


ppd . conso le 




pgo file 


printer 


ppd. pr inter 




pgo file 


quit 


pqt 


file 


pin Enter file name: 




ny 




L $c 




pnp 




pin Press RETURN. 




pgo menu 



= $a 

(Compare $ a to 3 ) 
(Equal: Quit routine ) 
(Not Equal: Compare to 2 ) 
(Equal: Printer routine ) 
(Not Equal: Compare to l ) 
(Equal: Screen routine ) 
(Not Equal: Select routine) 



$c 
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To change several print values, make 
a print value file. 



You may want to change not only the print destination but other 
print values. One way to do this in Apple Writer is to create a print 
value file. Can you figure out how to modify the menu program to 
load a print value file for each option on the menu? Hint— you will 
need a statement that looks something like this: 

qCpr intval f i le 

Remember that you must also create print value files with the 
names your program will be looking for. Can you write a menu pro- 
gram that creates a print value file? See Appendix E for the solution 
to these programming puzzles. 
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In this chapter you will learn 

• how to convert a number in string form to a numeric variable; 

• how to add and subtract in WPL; 

• how to use counters and accumulators in a program; 

• how to use numeric variables to control a loop; 

• how to create and number an address file; 

• how to produce personalized form letters. 

What Is a Numeric Variable? 

Like string variables, numeric variables can be set from the keyboard 
or from within a program. Unlike string variables, you can do 
arithmetic with numeric variables. The three WPL numeric variables, 
( x j , ( y ) , and ( z ) , may be substituted for text in WPL and Apple 
Writer commands. There is also a special set of commands associ- 
ated with them. 

A numeric variable has the following characteristics: 

• It may represent zero or any positive integer from 1 through 
65,535. 

• The variable name may be either upper- or lowercase and is 
always enclosed in parentheses: ( x ) , ( Y ) , or ( z ) . 

• If the value of the variable is increased or decreased so that it 
becomes zero, conditional execution causes the next statement 
to be skipped. (In WPL's arithmetic system, 65,535 + 1 = 0. This 
is known as overflow.) 

• Setting the variable to zero (as opposed to increasing or 
decreasing it to zero) does not cause the next statement to 
be skipped. 
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The Set X Command 



The command that performs arithmetic manipulation of numeric 
variables is called Set X. (There are actually three commands— Set 
Adding and subtracting with variables X, Set Y, and Set Z— one for each variable. They function identically.) 

The format of the Set X command is 

PSX number 

where number may be signed or unsigned. When the number is 
unsigned as in 

PSX 35 

the variable is given the value of number— in this case, [ x ) is set to 
35. When the number is signed as in 

psz + 10 

psy - 200 

the variable is modified by the value of number according to the 
direction of the sign— in this case, 10 is added to the current value of 
( z j and 200 is subtracted from the current value of ( y j . 



Converting Strings and Performing Arithmetic 

The age program, following, shows how numeric variables are used 
in WPL. This program figures out your age from information you 
type in response to Input statements. The information is entered as 
strings, converted to numeric form, used in arithmetic, and displayed 
as output text. In the age program, your birth year and the current 
year are converted to the variables ( X ) and ( v ) respectively, i X i is 
then subtracted from ( v i to approximate your age. If you have not 
had a birthday in the current year, 1 is subtracted from the answer. 

Example: how old are you? AGE PND 

PPR [N ] 

PIN ENTER YOUR BIRTH YEAR = $a 

PIN ENTER THE CURRENT YEAR = $b 

PIN HAD A BIRTHDAY YET THIS YEAR | Y or N)? = ic 
PSX Sa 
PSY $b 
PSY -(X| 
PCS /$c'N/ 
PSY -1 

PIN YOUR AGE RIGHT NOW IS ( Y | • 




Chapter 6: Using Numeric Variables 



The statement 

PSX $a 

takes the value of the $a string and converts it to a numeric variable, 
i x i . As you see in the final statement, a numeric variable may also 
be used as text. 



Using Counters and Accumulators 

One advantage of WPL is that it allows you to perform repetitive 
Apple Writer functions. Sometimes these functions need to be per- 
formed a given number of times. Numeric variables allow you to 
control the number of times a routine or loop is performed. They also 
serve as accumulators for numeric values collected during the loop. 

Let's say that each year on your birthday your company will give 
you a gift of stock, one share for each year of your life. You can write 
a WPL program that calculates the total number of shares you'll 
receive in the next five years. In fact, since the hge program collects 
all the necessary data, your stock calculation can be added to the 
end of that program. Here's what the additional statements would 
look like: 



Example: cumulative addition, counting CALL P Calculate Total Stock Over 5 Years 
down PS2 5 

PSX 
LOOP PSY +1 

PSX +(Y) 
PSZ -1 
PGO LOOP 

PIN In 5 years you will have ( X j shares of stock 



The crlc routine uses the ( z ) variable to control the number of 
times the calculation is performed— once for each year, or five times 
in all. Taking advantage of the conditional execution that occurs 
when a variable is decreased to 0, crlc begins by setting (Z) to 5. 
Then it subtracts 1 from ( z j each time the loop section is executed. 
When ( z j becomes 0, the Go command at the bottom of the loop is 
skipped and the answer is displayed. 



The Set X Command 



The ( x i variable contained the birth year in the first part of the pro- 
gram, crlc doesn't need that information anymore, so it reuses ( x ) 
as the accumulator— the bucket where it adds each year's number 
of shares, crlc initially sets ( x j to in order to clear out the pre- 
vious information. 



Warning 

Always give numeric variables an initial value before adding or subtrac- 
ting. You can provide an initial value by issuing a Set X command or by 
converting a string variable to a numeric variable. (Setting a numeric 
variable to doesn't cause the next statement to be skipped.) 



The ( y j variable already contains your current age, which will be 
increased by 1 each time the program executes the loop. Because 
you want to start counting with your next birthday, crlc must add 1 
to the ( y ) variable before doing the stock accumulation. (If you 
wanted to start counting with the current year, where in the loop 
would you increase the variable? See Appendix E for the answer.) 



Comparing Numeric Variables 

You can compare a numeric variable to another numeric variable 
by using the Compare Strings command. You can also compare a 
numeric variable to a numeric constant or to a string variable, pro- 
vided the constant or string consists of an integer between and 
65,535. First, though, you must convert the numeric variables to 
string format using the Assign String command. 

Comparing numeric variables gives you a way to end a loop without 
decreasing a numeric variable until it reaches 0. Let's change the 
crlc five-year stock calculation routine so that it uses this alterna- 
tive. (Remember that this routine is an addition to the rge program 
which is listed earlier in the chapter.) Here's how newcrlc looks as it 
performs the calculation for any number of years: 



NEWCRLC P Calculate Total Stock Over N Years 

PIN HOW MANY YERRS WILL YOU RECEIVE STOCK? = $a 

PSZ 

PSX 
LOOP PSY +1 

PSX +(Y j 

PSZ +1 

PRS(Z) - $b 

PCS /$b/$a/ 

PGO END 

PGO LOOP 

END PIN In $a years you wi 1 1 have ( X ) shares of stock 
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In the original stock calculation routine calc subtracted 1 from ( z ) 
until the value of (Z) was 0. In the new routine newcrlc begins with 
and adds 1 until the value of (Z) is equal to the number of years 
that was input in $a. In order to make the comparison, newcrlc must 
convert ( z j to a string variable, $t>, which is then compared to the 
original input value in $a. As long as the two strings are not equal, 
the pgo end statement is skipped and the program returns to loop. 
When the strings are equal, the loop is exited and the final answer is 
displayed. 

When newcrlc converts ( z ) to $b, the contents of the ( z i bucket are 
not changed. When the program is executed, Apple Writer just looks 
at the value of the numeric variable and sets the string variable to 
that same value. 

Creating Form Letters With WPL 

You now know all the commands needed to create your own per- 
sonalized letters. This section contains two sample letter-writing 
programs. The first program, number, numbers an address file so 
that it may be used for form letter input. The second, write, uses 
the numbered address file and a form letter file to write personalized 
letters. To begin, let's look at the form letter itself. 



A Sample Form Letter 

Here's what a very simple form letter looks like. Your own letter, of 
course, might be several pages long. 

(Date J 

( Address ) 

Dear ( Name) : 

Your back- ordered merchandise has been received andwill be 
shipped today by parcel post. Thank you for your order. 

Sincerely, 

Catalog Sales Distributors, Inc. 

The date, address, and name are the portions of the form letter that 
will be customized. You type the date; the address and name are 
contained in an address file. The write program assumes that this 
letter is stored in a file called letter on the disk in drive 2. 
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Creating an Address File 



The address file, oldrd, consists of a name and address for each 
customer. The file is named OLDflD because that's what it's called in 
the number program later in this section. An address may contain 
any number of lines. Each line ends with (return) . 

Because WPL has to be able to identify where each address begins, 
Marking the beginning of a name we use the convention of beginning the name line with a pair of 

angle brackets. A left angle bracket marks the end of the file. The file 
looks like this: 

< >Charles Gee 

34B Sansome Street 

San Francisco, CR 94111 

OMarilyn Bee 

12570 Pacific Blvd. 

Santa Monica, CR 90002 

OSerendi P. Tee 

RFD 3 Box 12 

High Point, OR 97567 

< 

There are two steps in creating an address file: (1 ) type the 
addresses, and (2) number the addresses. The form letters will be 
printed in whatever order the addresses are stored in the file. 

Note: You don't have to arrange the addresses in any special order such 
as by zip code or last name , but adding new addresses and finding 
addresses for corrections is easier if the file is in some order. 

Once the address file has been created, the addresses must be 
consecutively numbered because the write program uses the 
numbers to step its way through the file. If you add an address in 
the middle of the file, all the addresses that follow the new one must 
be renumbered. The number program saves you from this tedious 
clerical effort by doing the job automatically. 
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The number program, shown below, assigns consecutive numbers 
to the address file, oldrd. Each time it finds a < > marker, it inserts 
the next consecutive number between the angle brackets. The ( x ) 
variable is used for numbering the addresses. When all the 
addresses have been numbered, the numbered address file is saved. 
The numbered file is given a new name, newrd. (That way if your 
computer loses power during the save operation, you won't lose the 
original file.) 

number psx 1 
ny 

L .d2^oldad 
b 

Example: numbering a list 1 oop f /< > / < ( x ) > / 

y? 

pgo found 

pgo qui t 
found psx +1 

pgo loop 
quit s .d2/newad 

As the number program runs, you can watch the numbering process 
on the screen. If you want to speed up the program, use the No 
Display command at the beginning of the program to eliminate the 
screen output. 

After the number program runs, the newrd file looks like this: 

< L >Charles Gee 
34B Sansome Street 
San Francisco, Cfi 94111 
<2>MarilynBee 
12570 Pacific Blvd. 
Santa Monica, CR 90002 
<3 >Serendi P. Tee 
RFD 3 Box 12 
HighPoint, OR 97567 
< 
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A Form Letter Program 



The write program creates a form letter for each address in the 
newad file created by the number program. A section-by-section 
explanation of the write program follows; first, here's the entire 
program: 

Example: form letter processing Write pnd 

W*r h 1 

psx 1 

ppr ***** form LETTER PROCESSOR ***** 
pin Enter current date: = $a 
Loop ny 

L .d2^1etter 
b 

f ! ( Date l !fa! 

f/( Address)-"/ 

L . d2/newad!< (x) >!< !n 
pgo Name 
pgo Qui t 
Name f x ( Name ) 

L . d2x n ewad ! < { x j > ! ! n 
pnp 
psx +1 
pgo Loop 
Quit ppr[g][g][g] 
psx -1 

pin The number of letters printed was ( x I . 

As you read the detailed description of the write program, which 
follows, study the WPL statements that correspond to the functions 
described. You will find a syntax summary and examples for each 
command in Appendix C. 
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The Write Section 

Here's the Write section of the wri te program: 

Write pnd 

Ppr [ N ] 

psx 1 

ppr ***** FORM LETTER PROCESSOR ***** 
pin Enter current date: = $a 



The program begins by turning off text display, clearing the screen, 
setting the address file counter to 1 , displaying the program title on 
the screen, and prompting for the current date, which is used in 
every letter. These functions are performed only once; therefore 
they are not included in the loop. 

The Loop Section 

Here's the Loop section of the write program: 

Loop ny 

L .d2/ letter 
b 

f ! (Date) !$a! 
f/(Rddress)// 

y* 

L .d2/newad! < (x) >•< !n 
pgo Name 
pgo Qui t 

The processing loop extends from the beginning of the2 Loop section 
to the end of the Name section. The text buffer is cleared and a fresh 
copy of the form letter is brought into memory. The cursor is placed 
at the beginning of the letter. The first [F]ind command inserts the 
current date. The second [F]ind command places the cursor at the 
( fiddress ) tag and deletes the tag. 



A Special Note: You might be accustomed to using - as a delimiter, but 
there are times when it cannot be used. For instance, if you are loading 
segments of a file, you cannot use the ' as your delimiter, since it is an 
integral part of the file name (i.e., . d2/). You also don't want to use as 
a delimiter when it might appear elsewhere in the argument. For 
instance, the write program uses ! delimiters instead of the usual / 
delimiters in the [F]ind command for the date because you may want to 
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Alternate delimiters are necessary because of the way Apple Writer 
executes a command that contains a variable: first the variable 
name is replaced by the current value of its bucket, then Apple 
Writer executes the command. If the bucket happens to contain 
characters that match the delimiter, you won't get the results you 
expect. These two examples show how a poor choice of delimiters 
can get you into trouble: 



1. Command: 

Current Value of $a: 
The Command as Executed: 
What Happens: 



fV( Date)/$a/ 
9/17/77 

f/( Date J/9/17/77/ 

(Date) is replaced 

by 3 — the rest of 

the command is ignored. 



2. Command: 

Current Value of $B: 

The Command as Executed: 

What Happens: 



F !$B! 

DECEMBER ! ! 

F! DECEMBER! ! ! 

December is deleted. 



To avoid problems, don't choose a delimiter that might appear 
elsewhere in the argument. Table 6-1 shows you what delimiters 
you may use in specific situations. 

Table 6-1. Table of Delimiters 

Delimiter Any Length Carriage Return Any Character (Wildcard) 



/ none none none 

! none none none 

< = < ? 

# $ % & 

& ' ( ) 

+ 



The ( x j variable is used as an index to the address file. ( ) is set to 
1 in the Wri te section and increased by 1 in the Name section. The 
second [i_]oad command searches the address file for the current 
address marker and loads the address, not including markers, at 
the current cursor position. This form of [i_]oad causes conditional 
execution because [i_]oad may or may not find the text it's looking 
for: if the address marker is found, execution continues at the Name 
label; if not found, execution continues at the Quit label. 
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The Name Section 

Here's the Name section of the write program: 

Name f/ ( Name | 

y? 

L .d2/newad« <(;<]>! !n 
pnp 
psx +1 
pgo Loop 

The [F]ind command places the cursor at the (Name) tag and deletes 
the tag. Then the same address that was loaded in the Loop section 
is loaded again. This time, however, the ending marker is a space 
character, so only the first name of the address is inserted into the 
document in memory. The program assumes that the [L]oad opera- 
tion is successful— if the address was found in the Loop section, it 
will certainly be found again. 

The form letter is now complete, so it is printed. The program adds 
1 to the address file index and goes to the top of the loop. 

The Quit Section 

Here's the Quit section of the wri te program: 

Quit ppr [g] [g] [g] 

psx -1 

pin The number of letters printed was ( x) . 

This section is executed when the value of ( > ) is one higher than 
the number of the highest index in the address file. That signals the 
end of the job. The Quit section rings the bell three times to notify 
the operator that the printing is complete. Then, in order to display 
the correct number of letters, 1 is subtracted from (x). Finally, 
a message is displayed. 
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dvanced Techniques 



This chapter covers four advanced techniques: subroutines, chain- 
ing, startup, and loading the catalog into memory. It is possible to 
make effective use of WPL without ever needing these techniques. 
You will find that subroutines and chaining are of value, however, if 
you plan to write programs that are very large or very complex. You 
will find startup useful if you perform the same commands or run 
the same program every time you boot Apple Writer. You will find 
loading the catalog useful if you want to print it or save a copy of it 
on disk. 

In this chapter you will learn 

• what subroutines are and how to write them; 

• how to use subroutines to save memory; 

• how to write WPL programs larger than the 2,048-character limit; 

• how to add a startup program to Apple Writer; 

• how to put a copy of the catalog into memory. 
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Writing Subroutines 

In a large program, identical sets of statements are often needed in 
more than one place. Subroutines provide a means of writing these 
statements in one location and accessing them from anywhere in 
the program. Figure 7-1 shows the flow of control from several 
places in a program to a subroutine and back again. 



Figure 7-1. Subroutine Flow of Control- 



Si PSR ALPHA 
^> ••• 
• • • 




• • • 

S2 PSR ALPHA 
X> • • • 

• • • 



PSR ALPHA ^ 

• • • 

• • • 



MAIN PROGRAM 




A subroutine is self-contained: it has only one beginning and one 
end. It is part of a WPL program but functions as if it were a separate 
program. Go commands are allowed within a subroutine but may 
not refer to a label outside the subroutine. 



The Subroutine Command 

The first statement of a subroutine is a labeled statement. The label 
is the name of the subroutine. The Subroutine command says, "Go 
to the labeled statement and begin executing at that point." In this 
sense the Subroutine command works just as the Go command 
does. The difference is that the Go command causes a permanent 
transfer of control to a different place in the program. The Sub- 
routine command causes a temporary transfer of control; when the 
subroutine has finished executing, control is automatically returned 
to the statement following the Subroutine command. 
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Every subroutine contains a Return 
command. 



The format of the Subroutine command is 

P5R label 

Programmers talk about calling subroutines or calling programs. A 
call is a transfer of control. The Subroutine command calls the 
routine named in its argument. A subroutine may not call itself. For 
instance, a subroutine named suex may not contain the following 
statement: 

PSR SUBX 

Later in this chapter you will learn how to use the Do command to 
call another program. 



The Return Command 

Execution of a subroutine is initiated by a Subroutine command and 
ended by a Return command. The Return command causes the 
statement after the Subroutine call to be executed; execution then 
proceeds sequentially. 

The Return command must be the last statement executed in any 
subroutine. (It can appear anywhere within the subroutine, as long 
as it is the last statement executed.) There may be more than one 
Return statement in a subroutine, just as there may be more than 
one Quit statement in a WPL program. 

The format of the Return command, which takes no argument, is 

PRT 
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Sequence of Execution 

Figure 7-2 illustrates the order in which statements are executed in a 
program using a subroutine. 



Figure 7-2. Execution Sequence of a 
Subroutine 
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When a subroutine is called, Apple Writer searches for the 
subroutine label beginning at the first statement. For the sake of 
efficient execution, subroutines should be placed near the start of 
the program and the most frequently accessed subroutine should be 
placed first. 

The only valid way to enter a subroutine is by means of a subroutine 
call; that is, an SR command. You may not Go to a subroutine label 
or enter a subroutine as the next sequential instruction in your 
program. If you do, the results are unpredictable. For instance, a 
program may not begin with a subroutine. (If it did, the Return 
command would have nowhere to return to.) Use the technique 
shown in Figure 7-2, where the first statement is a Go command that 
sends control to the start of the main program. Place all subroutines 
between the Go command and the main program. 
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Chaining Programs 



About program length A WPL program may not be longer than 2,048 characters. Because 

WPL programs and footnotes share the same buffer, if the program 
prints a text file containing footnotes then the program is limited to 
1 ,024 characters. Most WPL applications will not be affected by 
these size restrictions. Occasionally, however, a program exceeds 
the limit. Chaining is a method of writing such a program by dividing 
it into two or more smaller programs that are linked together at the 
time they are run. 



Flow of Control With Chaining 

Chaining is accomplished when one program calls another using the 
Do command. Figure 7-3 shows how control flows from one pro- 
gram to another in chaining, ft, b, and c are separate WPL programs. 
Program ft can call either b or c. When a program is called, it replaces 
the calling program in the WPL buffer. B and c can return to h only by 
calling fl. In that case h starts over again from the beginning, not from 
the place where it called b or c. Unlike subroutines, which return to 
the statement after the Subroutine call, chaining always begins at the 
first statement of the called program 

Figure 7-3. Flow of Control With K 



Chaining. 
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77?e Do Command 

Chaining is done by issuing a Do command. The command may 
appear anywhere in the calling program. When it is issued, the called 
program replaces the calling program in the WPL buffer. Therefore 
any statements that follow the Do command in the calling program 
will not be executed. The format of the Do command is 

PDO .d2/f i lename 

where f i lename is the name of the called program. You are used to 
using the Do command as an immediate command that executes a 
WPL program. In chaining, the Do command is used as a deferred 
command. Exactly the same thing happens in both cases: the file 
named in the Do command is read into the WPL buffer, and execu- 
tion begins at the first statement in the buffer. 



Variables and Text During Chaining 

When one program chains to another, the calling program is no 
longer available. Variables and most buffers, however, remain un- 
changed. (The footnote buffer, which is shared with WPL programs, 
gets cleared when the called program is loaded.) Program a can 
read a document into memory and then call program B to modify the 
document. Program fl can also prompt for keyboard input and b will 
have access to the variables. 

^HaHHH^Bi STARTUP 

Refer to the Apple writer manual to learn If you have created a WPL program named startup on the disk that 
more about startup programs. contains your system print and system tab files, sys . prt and 

sys . tab, it will be executed automatically when you boot Apple 
Writer. Any program may be named or renamed startup. If you 
always run the same program after you boot, name it startup so that 
it is part of the boot itself. For instance, if you always run contprint, 
use the Rename File option of the SOS Command Menu to change 
the name of the program. (Make sure the file is unlocked before you 
try to rename it.) Here's how you would change the name of 

CONTPRINT tO STARTUP: 

1 . Press [□] to display the SOS Commands Menu. 

2. Type b to rename a file. 

3. Type contprint .startup and press [return] . 

4. Type startup and press (return ) . 
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How to Make a strrtup Program 

You may want to write your own STARTUP program to help you start 
up your system efficiently. This is a good idea if other people also 
run Apple Writer on your computer. For instance, here's a program 
that helps the user load the correct glossary file for various tasks 
without knowing anything about files or glossaries: 

Example: a startup program that startgloss p this is a STRRTUP program 

chooses a glossary pnc | 

ppr[ s ] 

ppr WELCOME TO RPPLE WRITER • 
ppr 

ppr Do you want to run . . . 

ppr a . Text edi t ing? 

ppr b. Repor t pr int ing? 

ppr c. Form letters? 

x ppr 

pin Type a, b, or c and then press RETURN. = $a 
pgo a 

pcs/$a/b/ 
pgo b 

pc5/$a/c/ 
pgo c 
pgo x 

a pasEDITGLOSS = $b 
pgo y 

b pasRPTGLOSS = $b 
pgo y 

c pasLTRGLOSS = $b 
y ppr 

ppr Make sure the GLOSSARY disk is in drive 1 . 

pin Then press RETURN . 

p load the correct glossary file 

qe.dlx$b 

pqt 

Type the strrtgloss program using Apple Writer and give it the 
name strrtup when you save it. You may save it on any disk except 
your Apple Writer Master Disk. The next section describes how to 
use a strrtup program such as this one. 
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How to Use a strrtup Program 



The strrtup program may be on the boot disk, or on any other 
Apple Writer disk. You may use different strrtup programs for dif- 
ferent tasks. There is only one restriction: The STARTUP disk must 
contain a sys . trb file and a SYS . prt file because otherwise you will 
get a SOS error. You may copy the standard versions of these files 
from the Apple Writer MASTER disk to your STARTUP disk, or you 
may create new ones using the Save Tab File and Save Print/Program 
Value File options of the Additional Functions Menu. To see this 
menu, press [□]. (For further information about sys. tab and 
sys . prt, see the Apple Writer manual.) 

Note: To copy the standard tab file from the Apple Writer MASTER 
disk to a data disk, follow these instructions: 

1 . Put the Apple Writer MASTER disk in drive 1 . 

2. Put the data disk in drive 2. 

3. Select the Additional Functions Menu by pressing [o]. 

4. To load the system tab file, type 

r.di/sys 

(h selects the Load Tab File option; sys is the name of the file.) 

5. To copy the system tab file, press [o] and type 

B.D2/SY5 

(b selects the Save Tab File option; sys is the name of the file.) 

6. You can copy the standard print value file in the same way, using the 



To use a strrtup program: 



1 . Put the Apple Writer MASTER disk in drive 1 and boot. 

2. When the Apple Writer copyright display appears, put the disk 
containing the strrtup program and the sys .trb and sys . prt 
files in drive 1. 

3. Press C return ) . 



That's all there is to it. 
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Loading the Catalog Into Memory 



In Apple Writer, you can load a disk catalog into memory so that 
you can print the text, modify it, search it, or save it. (Note: you can 
modify the copy of the catalog in memory, but that does not modify 
the disk's catalog.) This feature is also available in a WPL program. 
Here's how it works. 

First, enter the statement 

0R.D18 

This WPL statement consists of the following parts: 

Opens the SOS Command Menu . 

R Selects option R, the catalog option. 

. Dl Reads the catalog from drive 1. 

8 Puts the catalog in the text buffer . 

Now comes the tricky part. Apple Writer doesn't load the catalog all 
at once; instead, it loads a screenful and then waits for you to type 
a space or press ( return ) . That's fine when you use [ o ] rb as an 
immediate command, but when you use it in a program your pro- 
gram doesn't know in advance how many screens the catalog 
contains. Here are the statements that you must put after Ofl.Dlttto 
make sure you load the entire catalog into memory: 

(spaces) p (5 spaces) (return) 
(spaces) p ( RETURN ) 

Notice that both statements are in the comment format. The first 
contains five spaces because the catalog may contain up to five 
screens of information— and each space causes Apple Writer to 
load another screen. The [return) at the end of the first comment 
brings Apple Writer back to the SOS Command Menu. The (return) 
in the second comment causes Apple Writer to exit from the SOS 
Command Menu and execute the next statement in your program. 

The following crtrlog program reads a catalog of any length (up to 
five screens) and prints the catalog: 

Example: printing your catalog CRTRLOG NY 

P ( 5 spaces ) 
P 

PNP 
PQT 
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A Final Word 

As you continue to use Apple Writer and WPL, you'll see how WPL 
programs can simplify your writing and organizing tasks. Discover 
the power of WPL by experimenting. One good way to begin is to 
modify the sample programs written in thise manual. You can also 
change the programs that are provided on your Apple Writer disk. 
Chapter 8 explains how to modify programs, using the flUTOLETTER 
program as an example. 
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New programmers quickly learn that the easiest way to write a pro- 
The quick way to write a program: revise gram is to find one that does almost what you want it to do, and 
an existing one. then modify it. In this chapter you'll find out how to modify a program 

that someone else has written, using the hiitoletter program as an 
example. You will improve autoletter by giving it the ability to use 
titles (Mr., Ms., and so forth), and the ability to use first names and 
last names selectively in the body of the form letter. 

You will learn 

• how to understand a program that you didn't write; 

• how to use a workfile; 

• how to redesign a program; 

• how to test the modified program. 
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Understanding the rutoletter Program 

The ftUTOLETTER program, found on your MASTER disk, appears 
below. The numbers to the left of the WPL statements are not part of 
the program. We've added them so that you can easily refer to 
specific statements. 



1. 


START 


PSX 1 




2. 


LOOP 


NY 




3. 




L .D1/F0RNLETTER 




4. 




B 




5. 




F/( Address)// 




6. 




Y? 




7. 




L .Dl/ADDRS! < (X)> !<!N 




8. 




PGO FOUND 




9. 




PGO QUIT 




10. 


FOUND 


PLS .Dl/ADDRS! <[X)> ! !N = 


$A 


11. 




B 




12. 




F/(Name)/$fVA 




13. 




PNP 




14. 




PSX +1 




15. 




PGO LOOP 




16. 


QUIT 


PIN[\] Done at address (X) 


(press RETURN) 


17. 




NY 





The Structure of rutoletter 

The first thing to look for is the structure of the program. That is, 
what is the basic outline of the program logic? To acquire an 
understanding of any WPL program, answer these questions: 

Basic elements of a wpl program • What files does the program use? What do they look like? 

• What printed output does the program produce? What screen 
output and keyboard input? 

• What calculations are performed? 

• What is the main processing loop? (What does the program do?) 



IB 
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rutoletter Files 

Scan the program listing looking for [L]oad, Load String (ls), and 
[s]ave commands— commands that refer to files. Statements 3, 7, 
and 10 contain references to the formletter file and the rddrs file. 

Note: When analyzing a program, print every file the program uses. If a 
file is very long, print just the beginning and the end of it. 

The formletter file is printed below: 

( fiddress ) 
Dear ( Name) : 

Congratulations on your purchase of an 
Apple computer. You and your family 
will spend many enjoyable and 
instructive hours with your new 
personal computer. In today's 
fast-paced high-technology world, 
(Name) , you can' t afford to be without 
one. find you can rest assured that 
when you use an fipple computer, you' re 
using the best there is. 

Best wishes , 

The Folks at fipple Computer 

. infiddress number ( X ) ( press return | 
- FF 



Understanding the AUTULETTER Program 



In order to understand the structure of the rutoletter program, 
study the structure of its files. Notice the following things about the 

FORMLETTER file: 

• It contains the text of a letter. 

• It contains two words in parentheses: ( Address ) and ( Name ) . 
(Name) appears throughout the letter. 

• It contains an embedded Input command, which refers to address 
number (X) . This implies that the numeric variable i x j is set in 
the rutoletter program, and also that rutoletter will stop after 
each letter is printed and wait until f re turn) js pressed. 

• It ends with an embedded . ff (formfeed) command. When the 
form letters are printed, . ff causes the printer to skip to the top 
of the page so that each letter begins on a new page. 

Next, look at the rddrs file. The beginning and end are shown below: 

< 1 > John Smith 
123 Elm Street 
Rnytown, U.S.R. 12345 

< 5 >f1ary Sanders 
00000 Null Result 
Meander, OH. 54637 

< 

Notice the following things about the rddrs file: 

• It contains a series of four-line addresses consisting of name, 
street address, city and state, and zip code. 

• Each address begins with a number enclosed in angle brackets. 
The addresses are consecutively numbered. 

• The file ends with a left angle bracket. 
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Printed Output 

To find out what the program prints, first look for New Print (np) and 
Continue Print (CP) statements. Then see what file is [i_]oaded 
before the print command is issued. It turns out that at statement 13 
the autoletter program prints the letter that was loaded from the 
formletter file at statement 3. 



Screen Output and Keyboard Input 

Screen displays usually provide choices for the user, control over 
printing, or information about the progress of the program. Screen 
messages provide clues to how the program works. To locate them 
in the autoletter program, look for Print (pr) and Input (in) 
commands. (Don't forget the embedded Input command you found 
in the formletter file.) 

The following is true of rutoletter: 

• There are no user choices because there are no Input commands 
that contain a string variable for input. 

• There is one message, at statement 16. It contains a number that 
is 1 greater than the number of the last address printed by 

the program. 

• The Input statement at the end of the form letter stops the pro- 
gram until you press ' return-; . it's there to allow you to change 
paper in the printer. If your printer uses continuous forms (paper 
that comes in a roll, like paper towels, or in a box of attached 
sheets), the embedded Input statement may be removed. 



Calculations 

Look for commands that set numeric variables— sx, sy, and sz. One 
of these commands at the top of the loop (just after the label that 
begins the loop) or at the bottom of the loop (just before a Go 
command) probably identifies a calculation that is part of the pro- 
Numeric variables control looping. gram structure. A numeric variable is often used to control a loop. In 

the calc routine in Chapter 6, for instance, the (Z) variable is 
decreased by one each time the loop is executed; when ( z ) reaches 
zero, looping ends. 
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Statement 14 in rutoletter adds 1 to the (X) variable. The following 
statements also use the ( x i variable: 

• Statement 1 initializes the value of the (X j variable by setting ittoi. 

• Statement 7 uses the i x j variable in a [L]oad command to search 
for a marker in the rddrs file. Substitute a value for the variable to 
see what the marker looks like: when ( x j is i, the marker is <l> . 

• Statement 10 uses the ( x ) variable in a Load String command to 
search for a marker in the rddrs file. ( x ) has the same value in 
statement 10 as it had in statement 7. 

Use of the ( x ] variable in the rutoletter program can be sum- 
marized as follows: 

• it is initialized to l, 

• it is used to locate text in the rddrs file, 

• it is increased by 1 at the bottom of the loop. 

The rddrs file reveals how the consecutive address numbers are 
related to the use of the ( x j variable in rutoletter. 



The Processing Loop 

Most programs do some main task over and over. For instance, 
a program that generates form letters prints the body of a letter over 
and over again. No matter how complex the processing may be, it 
can be summarized in a simple statement. Because you have ana- 
lyzed the inputs, outputs, and calculations of the rutoletter 
program, you can now define its main task. 

Look for Go commands in the program. The Go command deter- 
mines what statement is executed next. Notice whether it is 
associated with conditional execution of a previous statement. 
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There are three Go commands in rutoletter: 

• Statements 8 and 9 each contain a Go command. These state- 
ments are associated with the preceding [i_]oad, which searches 
for a marker. If the marker exists in the formletter file, the pro- 
gram proceeds to the found label at statement 1 0; if not, it 
proceeds to the quit label at statement 1 6. Statements 8 and 9 
together represent a conditional transfer of control: the next 
statement to be executed depends on whether the [L]oad 
command finds the marker. A conditional transfer of control is 
like a fork in the road. See Figure 8-1 . 

Because there is no Go command after statement 1 6 sending 
control back to the processing loop, the program ends after the 
quit section is executed. 

• Statement 1 5 contains the third Go command. This statement 
represents an unconditional transfer of control. It always causes 
statement 2 to be executed next. An unconditional transfer of 
control is like a bend in the road. It causes the program to stop 
executing statements in a straight line, one after another, and go 
to a different place in the program. See Figure 8-2. 



Figure 8-1 . Conditional Transfer of 
Control: A Fork in the Road 
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Figure 8-2. Unconditional Transfer of 
Control: A Bend in the Road 




With what you've learned, you can now describe the processing 
loop. Here's what rutoletter does: 

• Sets ( x ) to 1 . 

• Loads a form letter into memory. 

• Loads address <i> from the rddrs file. If the address doesn't exist, 
time to quit. 

• Loads a name from address <i> and uses it to replace every 
occurrence of (Name) in the form letter. (See statements 10 
and 12.) 

• Prints the form letter. 

• Adds 1 to ( x j , so that the next address will be <2> . 

• Goes back to the top of the loop and loads a fresh copy of the 
form letter. 

• Displays a message, clears memory, and ends the program when 
(X) is 1 more than the highest-numbered address in the rddrs file. 



When you have finished analyzing the program, prepare a brief sum- 
mary statement like this one: "rutoletter prints a customized form 
letter for every address in a consecutively numbered address file." 

rutoletter is a relatively simple program, but the technique you've 
just learned will work for any WPL program. 
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Running rutoletter 

You may be wondering why you didn't begin this process by running 
hutoletter. The reason is that sometimes a program modifies files, 
and if you don't know exactly what it does you don't want to 
change the files without making a backup copy. To back up the files, 
you need to find out their names by studying the program— as you 
just did. 

Before going any further, copy the hutoletter program and its two 
files to a set of files on another disk. Name the copies hutoletterz, 
formletter2, and HDDR52. These are the files that you will modify in 
the next part of the chapter. 

Now run hutoletter and see exactly how it works: 

• Make sure the Apple Writer MASTER disk is in drive 1 and that 
your printer is turned on. 

• Press [p]. To print the form letters on a printer, type pd . pp inter. 
To display them on the screen, type pd . console. Then press 

( RETURN ) . 

• Press [p]. Type do rutoletter and then press return) . 

• Press (Return) after each letter is printed. 

Modifying the rutoletter Program 

Modifying a program is easy ... but only if you do it in a methodical 
manner. There are four steps to take, no matter what kind of pro- 
gram you want to change or how complex the change is: 

Define your need and design a solution. 1 . Describe the problem or need. What do you want the program 

to do? 

2. Design a solution. Conceptually, what additions and changes to 
the program need to be made? What changes must be made to 
the files? What will the new output look like? 

3. Implement the solution. What specific program statements must 
be added or changed? What specific changes must be made to 
files used by the program? 

4. Test the solution. Does the output of the modified program match 
the results you defined in step 2? 

In the rest of this chapter you will follow these four steps in order to 
add new features to the hutoletter program. 



The program you're changing may 
modify the files that it uses. 
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Describing the Need 



autoletter takes information from an address file and creates 
personalized form letters. However, it does not provide for titles such 
as Ms., Mr., Dr., and so on. Therefore you might define what needs to 
be changed in the following way: 

autoletter should be able to address the recipient of a form 
letter by title and last name ("Dear Mr. Smith"). It should also include 
the title in the address portion of the letter ("Mr. John Smith"). 



Designing the Program Changes 

The design phase of a program change consists of two parts: 
changes to the program and changes to the files. It's best to tackle 
the parts one at a time. 

When you analyze the need statement, you may discover aspects of 
the situation that weren't obvious at first. For instance, autoletter 
can't address a letter to Mr. Smith unless it is able to distinguish 
among the different parts of the name in the addrs file. 

Distinguishing parts of the name turns out to be a major stumbling 
block. Looking at the formletter document, you can see that only a 
single form of the name is used. Statement 10 in the autoletter 
program shows that the name consists of whatever is between the 
end of the address marker and the next space character. This, 
presumably, is the person's first name. 
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What if you add a title to the beginning of the name line: 

< 1 > Mr. John Smith 

Now the information between the end of the address marker ( <i> ) 
and the first space is "Mr.". Good, because you want to be able to 
isolate that information. 

But how will RUTOLETTER get the first name in the name line? Can 
it say that the first name begins and ends with a space? No, because 
the first marker in a Load String statement must be unique in the file, 
and the space character is not unique. Therefore the first name in 
address < 1 > will always be used because that's the first occur- 
rence in the file of information beginning and ending with a space. 

If you think about it, you will see that this problem occurs no matter 
what part of the name line you try to isolate. Even if you insert 
markers into the name, such as 

< l>Mr.+John$Smith 

the markers are unique only within a given address. They would not 
be unique within the addrs file. 

What's needed is a file containing only the current address that 
rutoletter is working on. How in the world can we make that 
happen? The answer is, by creating a workf ile. 
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Workfiles 



A workfile is a file that a program uses over and over again. It's 
something like a blackboard. Let's say you're writing a book on 
mathematics and you want to prepare a list of answers to the prob- 
lems in the book. You might work a problem on your blackboard, 
record the answer, erase the blackboard and work the next problem, 
and so on. Once you've got the answer, you don't have any reason 
to preserve the means by which you arrived at it. 



Figure 8-3. The Workfile: A Kind of 
Blackboard 




7 osar.(tItle)(l name)\ 



THE FORM 
LETTER. 




THE ADDRESS 
FILE 
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Let's see if autoletter can make use of such a workfile. We 
must envision how the workfile would be used and determine 
whether such a use is possible in autoletter: 



How the Workfile is Used 



Why This Is Feasible 



Add the current address to the 
document in memory 
(the form letter). 



autoletter already 
does this. 



Save the current address in 
a workfile. 



[b]ave with markers saves 
a portion of a document. 



From the workfile, load the title, Because the workfile contains 



Insert the title, first name, and [F]ind with Replace option, 
last name into the form letter. 

Having demonstrated the feasibility of the proposed solution, you 
can proceed to look at the changes that must be made to the files. 

Designing the File Changes 

The files autoletter uses are 

FORMLETTER 
ADDR5 

During this discussion it will be helpful to have a copy of the 
formletter document in front of you, so print a copy or display the 
document on your screen or refer to the listings earlier in this 
chapter. 

Looking at the formletter document, you recall that it contains two 
variable elements, (Name) and (Address). In order to create the 
salutation "Dear Mr. Jones" it's necessary to identify specific name 
elements for the title and last name. Because the letter is informal, it 
would be nice to have the first name available as well. Therefore you 
decide to replace every occurrence of (Name ) with one of the 
following: 

Name Element Examples 

i Title i Mr.,Ms.,Dr.,Rev.,Gen.,Hon.,Sir,Miss,Mrs.,etc. 
( Fname i George, Carol Sue 

( Lname j Smith, Huck-Finn, van den Berg, Lloyd George 



first name, and last name into 
separate strings. 



only the current address, you 
can designate parts of the name 
with unique markers. 
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You list as many different examples as possible to ensure that the 
design solution covers all cases. 



Next, let's tackle the addrs file. That's a little trickier. Referring to the 
list of name elements, you see right away that the space character is 
no longer useful as a delimiter because it may be part of a first name 
(Carol Sue) or a last name (van den Berg). 

By the Way: The Fname element represents the name the person wishes 
to be addressed by. Carol Sue Davis may be known as either Carol or 
Carol Sue. It will be the responsibility of the person maintaining the addrs 



A worst-case example of a complex name line in the addrs 
document is 



< 1 > Ms. Carol Sue B. Davis-Robbs 



Your task now is to design a system, or algorithm, for marking the 
line so that autuletter can distinguish among the name elements in 
a Load String statement. Let's see what happens if you place the 
following symbols before each element: 

Symbol Element 

> i, Title i ... part of address marker 

@F@ (Fname) 

@M@ Middle name or ini t ial 

@l@ ( Lname ) ... end of name is f return ) 

The worst-case example would look like this: 

< l>Ms.@F@Carol Sue@M@B . @L@Davis-Robbs or 
< l>Ms.@F@Carol@M@Sue B.@L@Davis-Robbs 
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To determine whether these symbols will perform correctly as 
markers in a Load String command, check the worst-case examples 
against a table of markers: 

Beginning Marker Ending Marker Element 



> 6 (Title) 

@F@ 6 (Fname) 

@L@ ( RETURN ) (L name. ) 

From the table you can see that each element has a unique set of 
markers. If you want to test the solution in greater detail, make up 
some names using the examples in the table of name elements; then 
insert markers and examine the results to see if they satisfy the 
requirements you've stated. 

Warning 

When you choose a marker, don't choose a character that appears in 
your form letter! rutoletter will delete all marker characters in the form 
letter. 



Implementing the Solution 

Having stated how you're going to change rutoletter, you're ready 
to begin programming. Put the data disk containing your copy of 
AUT0LETTER2 in drive 1 . Load rutoletter2 into memory and make 
the actual changes as we talk about them in the manual. 

The first modification to the program is to insert a comment before 
statement 1 documenting the change: 

RUT0LETTER2 P MODIFIED VERSION OF RUTOLETTER 

Then change the filenames in statements 3, 7, and 1 to formletter2 
use new names for the modified files. and RDDRS2 so that your modified program doesn't try to use the 

original files that came with Apple Writer. 
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You're going to use all of rutoletter except statements 10, 11, 
and 12. These statements load the name from the address file and 
replace it in the document in memory. Instead, you want to load 
different name elements from a workfile and replace them in the 
document. 



RUTOLETTER 



1. 5TRRT P5X 1 

2. LOOP NY 

3. L .D1/F0RMLETTER 

4. B 

5. F/( Address)// 

6. Y? 

7. L . Dl/RDDRS ! < (X) > • < !N 

8. PGO FOUND 

9. PGO QUIT 

10. FOUND PLS .Dl/RDDRS! < (X) > ! !N = $R 

11. B 

12. F/(NameJ/$R/R 

13. PNP 

14. PSX +1 

15. PGO LOOP 

16. QUIT PIN [ \ ] Done at address (Xj (press RETURN ) 

17. NY 



To save the current address in a workfile, precede it with a unique 
marker such as ( ) . The first section of new statements inserts the ( j 
marker at the end of the formletter document in memory. The 
current address is then loaded, including markers. The following 
statements replace statements 10, 1 1 , and 12. 

FOUND E 
D 

P INSERT RETURN RND ( ) MARKER 

F< <>( )< 
Y? 

P LOAD CURRENT ADDRESS AT END OF LETTER 
L .D1/ADDRS2! < (X) >!< ! 
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The next section of the program places the cursor at the ( i marker 
and saves the current address in the workfile. 

B 

F'i H )/ 

P CREATE WORKFILE WITH CURRENT ADDRESS 
S .D1/W0RKFILE83K 

Y 



Now the name elements can be replaced in the form letter. 

P INSERT TITLE FROM WORKFILE INTO FORM LETTER 

PLS .D1/W0RKFILE! >!@!N = $D 

B 

F'( Title K$D/A 

P INSERT FIRST NAME 

PLS .D1/W0RKFILE!@F@!@!N = $D 

B 

F/(Fname)/$D/A 

P INSERT LAST NAME 

PLS .Dl/W0RKFILE<@L@O< N = $D 

B 

F/(Lname]^$D/A 

There are just two small housekeeping details left to take care of. 
First, you need to remove the markers that are embedded in the 
name. 

P DELETE MARKERS IN FORM LETTER 
B 

F/@F@/ yf\ 
B 

F/@M@/ /A 
B 

F^@L@/ /A 
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Next, you must delete the current address at the end of the letter to 
be printed. From the end of the letter, delete one line at a time until 
the ( ) marker is deleted. When it's gone, you know you've deleted 
the entire address. 

DELTEMP E 

P DELETE CURRENT ADDRESS AT END OF FORM LETTER 

X 

F/()/(]/ 
Y? 

PGO DELTEMP 

The finished program looks like this: 

AUT0LETTER2 P *** AUT0LETTER2 **** 

START PSX 1 
LOOP NY 

L .D1/F0RMLETTER2 
B 

fy[ Address)// 
Y? 

L .D1/ADDRS2! < (X) > ! < ! N 
PGO FOUND 
PGO QUIT 
FOUND E 
D 

P INSERT RETURN AND ( ) MARKER 

F<<>()< 
V? 

P LOAD CURRENT ADDRESS AT END OF LETTER 

L .D1/ADDRS2! < (X)> !< ! 

B 

F/()/( V 
Y? 

P CREATE .D1/W0RKFILE WITH CURRENT ADDRESS 

S .D1/W0RK FILE 08>< tt 

Y 

P INSERT TITLE FROM . Dl/WORKF ILE INTO FORM LETTER 

PLS . D1/W0RKF ILE ! > !@!N = $D 

B 

F/(Title)/$D/A 

P INSERT FIRST NAME 

PLS . Dl'WORKF ILE • 8F8 ! 8 ! N = $D 

B 

F/(Fname)/fD/A 

P INSERT LAST NAME 

PLS .Dl/WORKFILE<@L@< ><N - $D 
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B 

F/(Lname)/$D/A 

P DELETE MARKERS IN FORM LETTER 
B 

B 

F/@M@/ /ft 
B 

DELTEMP E 

P DELETE CURRENT ADDRESS AT END OF FORM LETTER 

X 

Y? 

PGQ DELTEMP 
PNP 
PSX +1 
PGO LOOP 

QUIT PIN [ \ ] Done at address (X ) ( press RETURN ) 
NY 



Testing the Solution 

In order to test the programming changes you've made, it's neces- 
sary to change the files autoletter uses so that they match the new 
version, autoletterz. 

In the addrsz file, the appropriate markers must be inserted in 
the name line, according to the table of markers, so that the 
addresses look like this: 

< 1 >Nr-.@F@John@L@Smith 

123 Elm Street 

Any town, U.S.A. 12345 

<5 >Ms.@F@Mary A 1 i ce@M@R . @L@Sanders 
00000 Null Result 
Meander, OH. 54637 

< 



Warning 

Be sure the last address in the hddrsz file ends with a < marker on a 
separate line. If the < marker is missing, the last form letter will not be 
printed. 
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Notice that address <5> has been changed to test one of the 
conditions you designed autoletter2 to handle: a first name that 
contains a space character. Check to see if there are other 
conditions that need to be tested, and add or change addresses in 
RDDRS2 so that all program modifications are verified. 

You must also change the formletter2 document to conform to 
autoletter2's algorithm for filling in the title and last name 
separately. Here's how the changed letter might look: 

( Address j 

Dear (Title) (Lname): 

Congratulations on your purchase of an 
Apple computer. You and the (Lname) 
family will spend many enjoyable and 
instructive hours with your new 
personal computer. In today's 
fast -paced high- technology world, 
( Fname ) , you can 't afford to be 
without one. And you can rest assured 
that when you use an Apple computer, 
you ' re using the best, there is . 

Best wishes , 

The Folks at Apple Computer 

. inAddress number (X J (press return) 
.FF 

Now run the enhanced version of autoletter: 
Press [p] 

Type DO .D1/AUT0LETTER2 

Press (return ) 

If you like watching the letter being personalized, leave the program 
as is. If you'd like the program to run much faster and don't need to 
see the document displayed, insert a No Display ( md i statement 
before the start statement. 



Chapter 8: Enhancing WPL Programs 



The final step in testing is to review the results. Was every letter 
printed correctly? If not, follow the debugging instructions in 
Appendix D, change the program or files as necessary, and run the 
test again. The letter produced for address <5> should look like this: 

Ms. MaryAliceR. Sanders 
00000 Nul 1 Resul t 
Meander, OH. 54637 

Dear Ms. Sanders: 

Congratulations on your purchase of an 
Apple computer . You and the Sanders 
family ui 1 1 spend many en j oyable and 
instruct ive hours with your new 
personal computer. In today's 
fast-paced high - technology world, 
Mary Alice, you can't afford to be 
without one. And you can rest assured 
that when you use an Apple computer , 
you ' re using the best there is . 

Best w ishes , 

The Folks at Apple Computer 
There are copies of the modified files on the UTILITIES disk 

( WPL . RUT0LETTER2 , F0RC1LETTER2 , and ADDRS2 | . YOU Can refer to 

these if you are having any trouble with your modified files. 

Summing Up 

In this chapter you have learned what steps to take to change a 
program so that it fits your needs. First you learned how to examine 
a WPL program and find out what it does. Then you learned how to 
design, implement, and test your modifications. You became familiar 
with workfiles, and you saw how using a workfile could expand the 
capabilities of WPL. 

You now have all the tools you need to be an effective, efficient, 
innovative WPL programmer. But you haven't learned all that WPL 
can do for you. The power of WPL is that you can tailor-make pro- 
grams to suit your own Apple Writer requirements. Need a program 
that sends out customized memos? formats TV and movie scripts? 
keeps track of all your Apple Writer files? Whatever it is, you're ready 
to design it, write it, and let the player piano work while you play. 
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Appendixes 



yntax of WPL Statements 



A WPL program contains one or more statements. A statement may 
contain a WPL command, an Apple Writer command, or a comment. 
Any statement that does not contain a recognizable command is 
ignored when the program is executed. Every statement must end 
with ( RETURN ) . 

The General Format of a Statement 

The format of a statement is 

LABEL Space(s) COMMAND NAME Space(s) ARGUMENT ( RETURN ) 

The label must start in the leftmost position of the line. One or more 
spaces are required between the label and the command name. If 
there is no label, one or more spaces must precede the command. 
The rules governing spaces between the command name and the 
argument vary with the command: for Apple Writer commands, use 
spaces just as you would if you entered the command as an 
immediate command; for WPL commands, whether or not you need 
spaces between the command name and the argument depends on 
which command you're using: 

• commands that do not take an argument: CP, nd, np, qt, rt, yd 

• commands in which each space counts as a character: as, in, pr 

• commands in which spaces are optional and have no effect: cs, dd, 

GO, LS.SR, SX.SY.SZ 

Upper- and lowercase letters may be used interchangeably except in 
label references and (in certain cases) arguments. 



The General Format of a Statement 




Labels 



A label is a name given to a WPL statement. The label is optional; it 
may be any length and may contain any characters except spaces. 
Upper- and lowercase letters in a label are significant: label and 
label are not considered the same. 

Commands 

A command may be an Apple Writer command (see the Apple Writer 
manual) or a WPL command (see Appendix B). 

Apple Writer commands are entered in programs in exactly the same 
way as you would enter them as immediate commands with one 
important exception: you don't have to press (control ) . That is, 
[L]oad is entered as L, [r]ind is entered as F, and so on. 

WPL commands are always preceded by a p when entering them in 
programs. The p stands for [p]rint/Program. Thus, the New Print 
command is entered as pnp. 



Arguments 

Some commands take arguments, others do not. For Apple Writer 
commands, refer to the Apple Writer manual. For WPL commands, 
see Appendix C. The argument for an Apple Writer command may 
contain a 1 return] and may therefore appear on more than one line. 



( RETURN ) 

Every statement must end with (returnj . 

If (return appears on a line by itself, it is ignored. Therefore if you 
need two f return) s in a row— for instance, to exit from a menu- 
precede the second ( return ) with at least one space or other 
noncommand character. 

Variables 

There are three numeric variables and four string (text) variables in 
WPL. Numeric variables represent unsigned whole numbers. String 
variables represent one or more characters of text. 
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String Variables 



The string variables are represented as $h, $b, $c, and $d. They 
may be either upper- or lowercase and are always preceded by a 
dollar sign. Each string variable may contain up to 64 characters of 
text. A string variable may be used in place of text in any command. 
The value of the variable at the time the command is executed 
replaces the variable name. 



Numeric Variables 

The numeric variables are represented as i x i , ( y ) , and (Z). They 
may be either upper- or lowercase and are always enclosed in 
parentheses. They may be increased, decreased, or set to any 
integer from to 65,535. If the maximum number is increased by 1 , 
the result is 0; this is called overflow. When a statement increases or 
decreases a numeric variable to 0, the next statement is skipped. 
When a statement sets a numeric variable to 0, the next statement is 
executed. 



Constants 

A constant is a string that always has the same value. Its value 
does not change while the program is running. For example, in 
a command that adds 1 to a numeric variable, "1" is a constant; 
in a command that displays hello on the screen, "hello" is 
a constant. 

Comments 

A comment line may be inserted anywhere in your WPL program. By 
convention, a comment begins with the following characters: 

space(s) P space(s) 

Any statement that is not recognized as a WPL command or an 
Apple Writer command is assumed to be a comment and is ignored 
during execution of the program. A comment may not appear on the 
same line as a command. 
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List of WPL Commands 



Deferred Commands: Apple Writer does not immediately execute 
deferred commands when you type a WPL program. They are 
executed when the program that contains them is run. All of the 
commands listed below may appear as deferred commands in a 
WPL program, preceded by the character P. For example, pnp. 

Immediate Commands: Immediate commands are executed as soon 
as they are typed at the keyboard. Commands listed below with an 
asterisk in column I may be executed immediately from the 
keyboard, preceded by [p]. For example, press [p] and then type 
np followed by C ^urn) . 

Embedded Commands: Commands embedded in a document are 
executed when Apple Writer encounters them in the course of 
printing the document. Commands listed below with an asterisk in 
column E may be embedded in an Apple Writer document, preceded 
by a period. For example, .in. 



Command I E Description 



fiS 




ASSIGN STRING (give string variable a value) 


CP 


* 


CONTINUE PRINTing the next file of a document 


cs 




COMPARE STRINGS 


DO 


* 


DO (execute) a WPL program 


GO 




GO to a labeled WPL statement and execute it 


IN 




* INPUT (display a message and wait for a reply) 


LS 




LOAD STRING 


ND 




NO DISPLAY of text on screen 


NP 


* 


NEW PRINT (first or only file of a document) 


PR 




PRINT (display) a line on the screen 


QT 




QUIT the program and return to Apple Writer 


RT 




RETURN from a subroutine 


SP 




SUBROUTINE call 


SX 




SET X (change the value of numeric variable X) 


SY 




SET Y (change the value of numeric variable Y) 


SZ 




SET Z (change the value of numeric variable Z) 


YD 




YES DISPLAY text on screen 
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ummary of WPL 
Commands by Function 



The 1 7 different WPL commands fall into four functional groupings: 

• Transfer of Control Commands— do, go,qt,sr,rt 

These commands affect the sequence of execution; the next 
statement to be executed is not the next sequential statement in 
the WPL program. Commands that cause a WPL program to start 
and end are included here. 

• Output Commands— display commands are pr, in, nd, yd 

—print commands are np, cp 
These commands allow the program to display messages, print 
documents, and turn the text buffer display on and off. 

• Numeric Variable Commands — sx, SY, sz 

These commands are used to set integer variables and change 
them by addition and subtraction. 

• String Variable Commands— as, cs, ls 

These commands are used to set string variables, compare two 
strings, and load a specified string from a file. 

This appendix tells you how to use each WPL command. The 
commands are grouped by function and covered in the order 
shown above. 

There is a fifth group that is composed of commands that also 
belong to other groups: 

• Conditional Commands— sx, sy, sz, cs, ls 

These commands affect the sequence of execution. Under 
certain conditions, the statement following the conditional 
command is skipped. Conditions that cause a statement to be 
skipped are described in this appendix in the usage section for 
each conditional command. 
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In order to use this appendix, you need to be familiar with the syntax 
rules of WPL (see Appendix A). 

Items in braces (j 1) are optional. 

Command Modes 

There are three ways (or modes) of using WPL commands: deferred, 
immediate, and embedded. Some commands can be used in more 
than one of these modes. Every command can be used in deferred 
mode— that is, in a WPL program. The command's argument is the 
same regardless of mode, but the command name must be pre- 
ceded by the character " . " in embedded mode or "p" in deferred 
mode. This section contains a definition of each mode and the 
command name syntax required for each mode. The command 
descriptions below give an example for each mode in which a given 
command can be used. See Appendix B for a table of the modes 
allowed for each command. 



Deferred Mode 

Syntax: Command name is preceded by the character P. 
Example: pdo 

Usage: p is the [p] in the Apple Writer [p]rint/Program 

command, but it is typed without pressing control i 
when entering a deferred command. Normally 
[p]rint/Program commands are executed as soon as 
they are entered. In deferred mode, however, these 
commands are treated as text; they are then stored in a 
file as part of a WPL program and are executed only 
when the program is run. 



Immediate Mode 

Syntax: Command name is preceded by [P]. 
Example: [p]do 

Usage: From Apple Writer, the command is executed 

immediately. The command is valid only when typed 
after pressing [p]. 



Embedded Mode 

Syntax: Command name is preceded by a period. 
Example: .in 

Usage: When embedded in an Apple Writer document, the 
command is executed when it is encountered in the 
course of printing the document. 
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Transfer of Control Commands 



do— Execute a WPL Program 

Syntax: DO . dl/ filename 

Examples: pdd .D2/chainprog 

[P]D0 .Dl/UPLPROG 

Usage: I n deferred mode, the current WPL program chains to a 
program called filename. 

In immediate mode, the WPL program called f i 1 ename 
is executed immediately. 



go — Execute a Labeled Statement 

Syntax: GO statementlabel 

Example: pgo loop 

Usage: Causes the statement named statementlabel to be 

the next statement executed, regardless of where in the 
program the statementlabel statement appears. 
Execution then proceeds normally. 



QT — Quit 

Syntax: qt 
Example: pqt 

Usage: When qi" is encountered, the WPL program is exited 
and control is returned to Apple Writer. 



sr— Subroutine Call 

Syntax: SR subroutinelabel 

Example: psr print 

Usage: Causes the statement named subroutinelabel to be 
the next statement executed. Execution then proceeds 
normally until a Return command is encountered. Note: 
a subroutine may contain a Subroutine Call. This is 
called nesting. Subroutines may be nested up to 32 
levels. 

A subroutine is not allowed to call itself. 
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rt — Return From Subroutine 



Syntax: rt 
Example: prt 

Usage: Causes control to be transferred to the statement 
following the Subroutine Call command that was 
executed last. 



Output Commands 

pr, in, nd, and yd govern screen output, np and CP govern 
printer output. 



PR — Print a Line 

Syntax: PR {message- text} 

Example: PPR ** Welcome to the Pr int Menu Program ** 

Usage: Causes a message line of up to 1 28 characters to be 

displayed on the screen. If no message text is provided, 
a blank line is displayed. 



in — Input a Line 

Syntax: {message- text} 
Examples: PIN Name of d ocument to be printed? = $A 

.IN Please insert special forms in printer 

Usage: Causes a message line of up to 1 28 characters to be 

displayed on the screen. If no message text is provided, 
a blank line is displayed. 

Causes the program to wait until ( return ) is pressed. 
A response may be typed before pressing ( return ) . in 
deferred mode, the program may test the response for 
a particular value. In embedded mode, any response 
followed by return causes the program to resume 
execution. 



Every character before the = sign is displayed, including 
space characters. The string variable ( $fi ) is not displayed. 
Any of the WPL string variables may be specified. The 
response is stored in the specified string variable. 
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nd — No Display of Text Buffer 



ND 
PND 

Prevents document in memory from being displayed on 
the screen. Use this command for faster processing of a 
WPL program. 

Provides full use of screen for PR and in commands. If 
nd is not specified, only a single line on the screen is 
available for output messages. 



yd — Yes, Display Text Buffer 

Syntax: yd 
Example: pyd 

Usage: Causes document in memory to be displayed on the 
screen. 

np— A/eiv Print 

Syntax: np 
Examples: pnp 

[P]NP 

Usage: Causes the document in memory to be printed. The first 
page is numbered according to the current value of 
Page Number ( pn j , which is described in the section 
on printing in the Apple Writer manual. 

cp— Continue Printing 

Syntax: cp 
Examples: pcp 

[P]CP 

Usage: Causes the document in memory to be printed. Page 
numbering continues from previous document. 



Syntax: 

Example: 

Usage: 
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Numeric Variable Commands 



sx sets numeric variable ( x j , sy sets numeric variable ( Y ) , and sz 
sets numeric variable (Z). The three numeric variable commands 
function identically; therefore, only sx is shown here. 

sx—SetX 

Syntax: sx n or sx +n or sx -n 

SX (Y) 
SX $R 

Example: psx +2 

Usage: n is a whole number between and 65,535 inclusive. 

If n is not preceded by a sign, the variable ( x ) is set to n. 
If n is preceded by a plus sign (+n), the value of n is 
added to ( X ) . If n is preceded by a minus sign ( - n), the 
value of n is subtracted from ( x ) . 

n may be a numeric variable. For instance, the state- 
ment sx ( y ) takes the current value of variable ( Y ) and 
places it in variable t x j . ( y ) remains unchanged. 

n may be a string variable. For instance, the statement 
sx $r takes the current value of variable $a, converts it 
to numeric format, and places it in variable ( x i . $h 
must represent a whole number between and 65,535. 

If n is signed and the new value of ( x ) is 0, the next 
statement is skipped. 

String Variable Commands 

The four string variables are $ft, $b, $c, and $d. In the syntax of the 
string variable commands shown below, the source string is on the 
left of the equals sign and the receiving string is on the right. The 
receiving string is shown by convention as $fi but may be any of the 
string variables. A string variable may contain up to 64 characters. 
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rs— Assign String 



Syntax: AS text-br- variable = $R 
Example: prs .di/ = $d 

Usage: The string variable on the right of the equals sign is 

given the value of the text, variable(s), or concatenation 
of text and variables, on the left side of the equals sign. 
A string variable may appear on both sides of the 
equals sign; in this case its original value is lost after the 
Assign String command is executed. In all other cases, 
the values of any variables on the left side of the equals 
sign remain unchanged. 



cs— Compare Strings 

Syntax: C5 /% ex t-or-variable' text -or -variable/ 

Example: pcs /$R/yes/ 

Usage: A slash (/) is usually used as the delimiter, but you may 
use any character that does not appear in the text. (See 
the discussion on delimiters in Chapter 6). The 
comparison results in one of two possible outcomes: 
EQUAL or NOT EQUAL. If the comparison is equal, no 
action is taken. If the comparison is not equal, the next 
statement is skipped. 



ls— Load String 

Syntax: LS f ilename'str ing-start !string-end! jn|{aj = $R 
Example: PLS .Dl/GETTYSBURG ! Fourscore! ago! = $R 

Usage: The file is searched for the first occurrence of string- 
start. Up to 64 characters are loaded from the file into 
the string variable. Loading ceases when str ing-end is 
found. If st ring -st ar t is notfound, the next statement 
is skipped. 



The Load String command is similar to the Apple 
Writer [i_]oad command and uses the same options: n 
means "do not include the markers in the string"; r 
means "load all occurrences." 
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rror Messages and 
Debugging Hints 



This appendix contains two sections. The first section explains 
every error message that WPL provides. The second contains hints 
on how to figure out why your program is not doing what you 
expected it to do. 

Error Messages 

If, while running a WPL program, Apple Writer comes to a condition 
that prevents it from executing the current statement, it stops and 
displays a message on the screen. This condition is known as an 
execution error. To leave the WPL program (which can proceed no 
further) and return to Apple Writer, press (return) 

Here is a list of WPL execution error messages. When the message 
appears on the screen, it is preceded by the words wpl Error and 
followed by the words (Press return i . 



Label not found --> xxxxx 

A Go command contained the label argument xxxxx, but no such 
label exists in the program. 

• Have you spelled the label correctly in the Go statement? 

• Did you type letter I for number 1 ? letter O for number 0? 

• Is the use of upper- and lowercase identical in the label and the 
label argument? 
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' RT ' without 'SR' 



A Return (rt) command was encountered, but there was no sub- 
routine to return from. 

• Did you enter the subroutine without calling it with a Subroutine 
(SR) command? For instance, did you enter the subroutine by 
Go-ing to it? 



Program > 2048 chars 

The WPL program is longer than 2,048 characters. (That is, the size 
of the WPL program exceeds the space allotted for it in Apple Writer.) 

• Refer to Chapter 7 for suggestions on using subroutines and 
dividing long programs. 



More than 32 'SR' 

More than 32 Subroutine (sr) commands were executed without 
a Return (rt) command. 

• Does a Go command in a subroutine refer to a label outside the 
subroutine? 

• Was the Return command bypassed? (Can the statement just 
before the Return statement cause conditional execution?) 

• Does the subroutine call itself? For example 

AAA PSR AAA or 

BBB P . . 

PSR BBB 
P. . 
PRT 



Footnote Overflow 

The WPL program tried to print more than 1 ,024 characters of 
footnote text on a single page, or a single line of footnotes contains 
more than 128 characters. 

• Is a footnote missing the end-of-footnote identifier " >}"? 

• If you need help in reducing the amount of footnote material on 
a page, see the Apple Writer manual. 
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Debugging Hints 

In addition to errors listed above that cause the WPL program to 
stop, there are others— known as logic errors — that do not stop the 
program but that produce unexpected results. These errors typically 
occur when 

• a command name or argument is mistyped 

• a WPL command is not preceded by P 

• duplicate labels exist and are referred to by a Go command 

• a syntax error occurs (see Appendix A) 

• a file does not contain the information your program expects 

• the program contains a design error 

• conditional execution occurs and a statement is unintentionally 
skipped 

The following sections describe techniques for correcting logic 
errors. 



Desk Checking 

Desk checking is pencil-and-paper work. It means taking a printed 
copy of your WPL program and a printed copy of the textfile, if any, 
and playing computer— reading each statement and writing down 
what happens when it is executed. Each time the value of a variable 
changes, write down the new value. Is it what you expected? After 
a command that causes conditional execution, which statement is 
executed next? 

This is the time to make sure the program syntax is correct. This is 
also the time to look up in the manuals any command whose format 
or use you are unsure of. When you find an error, check to see if you 
have made the same error in more than one place in the program. 
After you have corrected all the errors you can find by methodical 
desk checking, run the program again. You may have to go through 
this process a number of times if you are unfamiliar with Apple Writer 
or WPL 
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A trace is a kind of debugging diary displayed on the screen by your 
program. When a program is producing unexpected results and 
desk checking doesn't reveal where the error is, insert trace state- 
ments to display 

• the sequence of execution of program statements 

• changes in variables 

After your program is operating properly, you can remove the 
trace statements. 

You create a trace statement by inserting an ordinary WPL Print or 
Displaying the progress of a program Input statement in your program to display the progress of the pro- 
gram as it is executed. The Input command allows you to stop the 
program as well as print out the value of any variables you are using. 
A good place to put a trace is at the beginning of a loop or after 
a change in a variable. Here is a sample program with traces inserted. 
(Explanations are in the righthand column.) 



P5X 1 

LRBELR F/string// 
Y? 

PGO LRBELB 
PQT 

LRBELB PSY (X) 

PSY +1 

tracel PIN LRBELB , X is ( X ), Y is ( Y ) 

L .D2/TEXTFILE! (X j ! (Y) IN 

P5X +1 

trace2 PIN Rfter load, X is (X) 

PGO LRBELR 



Initialize x 



Go if string found 
Quit if not 

Y = X + 1 

Load text from marker 
x to y at cursor 

X = X + 1 



The trace statements are labeled traceiand trace2. Traceilets 
you know that the program is in the lrbelb routine and tells you the 
current values of ( x ) and ( Y ) . t r ace2 lets you know that text has 
been loaded and shows you the new value of ( x ) . 
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When you run the program with traces, the following messages will 
be displayed: 

LABELB , X is 1, Y is 2 
After load, X is 2 
LABELB , X is 2, Y is 3 
After load, X is 3 

(and so forth) 

You may also find it helpful during debugging to turn on the display 
of the document in memory by inserting a Yes Display (yd) com- 
mand or deleting a No Display (nd) command. 



i 
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nswers to Programming 
Questions 



Throughout the manual are programming puzzles and questions. 
Try working out the answers by yourself before you look them up in 
this appendix. 

Chapter 2 Answers 

The strr Program 

The strr program fills memory with stars by inserting the first star 
and then loading from memory. The strr program looks like this: 

STfiR p THIS PROGRAM FILLS MEMORY WITH STRRS 
ny 

p INSERT R STRR INTO MEMORY 

f //*/ 

loop e 

p LORD MORE STARS 
LH 

pgo loop 

To change the program so that it places *tt$ in memory, change the 
[F]ind statement 

from: f//*/ to: f//*o$ 
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Uppercase and Lowercase Responses 

The following routine goes to the qu i t label if any response except 
uppercase "Y" is typed: 

pin To print another file type Y, then press RETURN. = $a 
pes /$a/Y/ 
pgo print 
pgo qui t 

To change the routine so that it accepts lowercase "y" as well, insert 
the following two statements after the Compare Strings statement: 

pgo print 
pes /$a/y 

The modified routine looks like this: 

pin To print another file type Y. then press RETURN. - $a 

pes /$a/Y/ 

pgo print 

pes /$a/y/ 

pgo print 

pgo qui t 



Appendix E: Answers to Programming Questions 



Modifying the menu Program 

The menu program, shown below, displays a menu that allows you to 
select an output destination for your document: 



menu 


ond 




ppr [ \ ] 




ppr PRINT OPTIONS MENU: 




nnr 




ppr { 1 J Screen 




ppr ( 2 ) Printer 




ppr ( 3 i Qui t 




npr 

r IT 


sel ec t 


pin Select 1, 2, or 3: -$a 




pes /$a/3/ 




pgo qui t 




pes /$a/2/ 




pgo printer 




pes /Sa^l/ 




pgo screen 




pgo select 


screen 


ppd. console 




pgo file 


printer 


ppd. printer 




pgo file 


qui t 


pqt 


file 


pin Enter fi le name: = Sc 




p«y 




L $c 




pnp 




pin Press RETURN 




pgo menu 



To change the menu program so that it loads a print value file for each 
print option (screen or printer), you must change the screen routine 
and the printer routine so that they load the appropriate files. 

Print value files are loaded by means of Apple Writer's Additional 
Functions Menu. To use this menu, type [q] followed by the letter of 
the option you have selected. If you choose Option C (Load Print/ 

Program Value File) Or Option D (Save Pr in t 'Program Value F i le), 

Apple Writer asks you for the name of the file. 
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The print value file that contains the values appropriate to screen dis- 
play is called pvscrn. The print value file for the printer is called 
pvprtr. (The next section of this appendix tells you how to write 
a menu program that creates these print value files.) Replace the 
screen and printer routines in the menu program with the 
following: 



screen qc.D2/pvscrn 
pgo file 

printer qc . D2/pvpr t r 

pgo file 



qc.D2. pvscrn means 



q Open the Additional Functions Menu 

c Choose Option C: Load Print/Program Value File 

.D2/pvscm the file and drive (followed by return)) 



A Menu Program That Creates a Print Value File 

The followingPRTVRL program creates a print value file tailored to 
user specifications. The program shows how to create a print value 
file from a menu program. It is included here to illustrate a technique 
and therefore modifies only a few of the available print options, psp, 
ppd, and ppl are the WPL equivalents of embedded Apple Writer 
print commands .SP, .PD.and .PL. 
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PRTVAL p CREATE a print value file 
PND 

PPR [ ] 

PPR PRTVRL creates a print value file for 

PPR ( 1 ) Screen 

PPR (2 ] Printer 

WHICH PIN Select 1 or 2 - $A 

P BEGIN WITH STANDARD SYSTEM PRINT VALUES IN MEMORY 

PPR Put Apple Writer master disk in drive 1 , 

PIN then press RETURN. 

QC.D1/SYS 

PCS /$A/1/ 

PGO SCREEN 

PCS /$A/2/ 

PGO PRINT 

PGO WHICH 
SCREEN PPD. Console 

PSP1 

PIN How many 1 ines long is the screen display? = $B 
PPL IB 

QD .D2/PVPRTR 
PGO QUIT 
PRINT PPD. Printer 

PSP0 

PIN How many printed lines per page? = $B 
PPL $B 

QD .D2/PVSCRN 

QUIT PPR ***T he print value file uas created. *** 

PPR Toverify the new values, press RETURN and then 

PIN type CONTROL-P followed by ? 

PQT 

The prtval program loads the standard system print value file, 
prt .sys. Any values that are not modified by prtval have the 
standard system setting in the new print value file. 
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Starting the Stock Calculation With the Current Year 

The stock calculation routine looks like this: 

CALC P Calculate Total Stock Over 5 Years 

PSZ 5 

PSX 
LOOP PSY +1 

PSX +(Y) 

PSZ -1 

PGO LOOP 

PIN In 5 years you will have (X) shares of stock 

Each year on your birthday you receive your age in stock. The ( y ) 
variable represents your age each year. When the crlc routine is 
entered, (Y ) is your present age. At the loop label, (Yj is immediately 
increased by 1 and the result is then added to accumulator (X). That 
is, CftLC is designed to calculate the total stock you will receive on 
your next five birthdays. 

To redesign calc so that it begins calculating with your present age, 
not your age at your next birthday, add your age to the accumulator 
before adding 1 to your age. You can do this by switching the order 
of the two commands following the loop label: 

LOOP PSX+(Y) 
PSY +1 
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PL Programs in This 
Manual 



This appendix contains a list of all the programs and routines that 
appear in the manual. Some of the programs are on the Apple Writer 
UTILITIES disk with the prefix wpl . ; these are marked with an 
asterisk (*). 

*memoprt (Page 4) 

Prints a document from two files. 
hppend (Page 33) 

Makes three specific files into one. 
message (Page 34) 

Prints a selected portion of a file. 
srveprrt (Page 41) 

Saves part of a document in a new file. 
addon (Page 41) 

Adds a document to an existing file. 
pick (Page 53) 

Echoes whatever you type. 
rppend2 (Page 53) 

Makes any three files into one. 
getnrme (Page 56) 

Prompts for a value, searches a file, and displays the result. 
choice (Page 59) 

Prompts for an answer, compares it to valid responses. 
'menu (Page 60, 137) 

Prints a file on the printer or displays it on the screen. 
*rge (Page 66) 

Calculates current age from birth year. 
*crlc (Page 67, 140) 

Calculates a 5-year stock option. (Includes rge program.) 
newcrlc (Page 68) 

Another way of calculating a stock option. 
'number (Page 71) 

Assigns consecutive numbers to addresses in a file. 
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'write (Page 72) 

Creates a form letter. 
STRRTGL0S5 (Page 85) 

A Startup program that loads a choice of glossaries. 
rutoletter (Page (92) 

Prints form letters, inserting names and addresses from an 

address file. 
rutoletter2 (Page 108) 

Prints form letters, inserting names and addresses from an 

address file. 
prtvrl (Page 139) 

Tailors a print value file to specifications. 
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accumulators 67-68 

addon program 41, 141 

address files 70-71 

ADDRSfile 94, 104-105 

age program 66-67, 141 

algorithm 104 

analyzing programs 92-99 

append program 33-34, 141 

append2 program 53,141 

Apple Writer 

MASTER disk 4, 86, 92 
relation to WPL 4,10-12 

Apple Writer commands 
definition of 16 
how to write 16, 22-26, 1 1 6 

argument 

definition of 18, 19,21 
how to write 21,23, 116 
upper- and lowercase with 18 

Assign String command 54, 55, 
68,127 

autoletter program 92, 142 
analysis of 92-99 
modification of 99-1 1 1 
-AUT0LETTER2 program 108, 142 

blank line 42 
branching 37 
buffers 

definition of 10 

footnote 10,83,84, 130 

screen 11 

text 12,44-45,56 
bugs 12,131-133 



calc program 67-68, 141 
calling 

programs 84 

subroutines 81 
catalog program 87 
chaining programs 83-84 
choice program 59, 141 
clearing the screen 45 
columns 22 
command name 19, 21 
command statement 17 
commands 

deferred 8,119,122 

definition of 16.21 

embedded 5-7, 119, 122 

how to write 21 , 22-26, 116 

immediate 5, 16, 119, 122 

See also Apple Writer commands 

and WPL commands 
comments 

definition of 17 

how to write 27-28, 117 
Compare Strings command 58-60, 

68,127 
concatenation 54-55 
conditional execution 57-58 
constants 50, 117 
Continue Printing command 4, 42, 

95, 125 

Control Character Insertion mode 
43, 45 

converting strings 66-67 
counters 67-68 
creating programs 18 
cursor, moving the 23, 24 
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D 

Data Line 28 
debugging 12,131-133 
deferred commands 8, 119, 122 
deleting text 28 
designing changes 

to file 103-105 

to program 100-101 
desk checking 131 
disk 

MASTER 4.86,92 
STARTUP 86 

UTILITIES 3,4, 19, 111, 141 
display 12,42-45, 125 
Do command 84, 123 
documentation, internal 17, 20, 27 



editing programs 19, 28-29 

embedded commands 5-7, 119, 122 

ending programs 33-35 

erasing the screen 45 

error messages 34-35,129-130 

executing the last statement 33 

exiting 

from loops 37 

from programs 33-35 

Find command 25-26, 28, 75 
finding and replacing text 25-26, 28, 
75 

flow of control 

with chaining 83 

with subroutines 80 
footnote buffer 10, 83, 84, 130 
form letters 69-75 

See also autoletter program 
formletter file 93-94,103 

G 

generalizing a program 53 

getname program 56, 141 

Go command 35-37, 80, 96-97, 123 

H 

halt program 43 

halting programs 33-35, 43 

/ 

immediate commands 5,119,122 
implementing program changes 
105-109 

initial value, giving numeric variables 
an 68 



Input command 43,44,52-53,124 
inserting text 28 

internal documentation 17,20,27 
interruption due to error 34-35 



labels 

definition of 17, 19 

how to write 20, 116 

upper- and lowercase with 18 
last statement 33 
letter program 44 
Load command 19 
loading catalog into memory 87 
Load String command 56-57, 58, 

127 

logic errors 131-133 
loops 

processing 96-98 

program 35-37 
lowercase characters 18,50,136 

M 

MASTER disk 4,86,92 

memoprt program 3-4, 141 

memory 

clearing 24,29 
loading catalog into 87 
sharing with Apple Writer 10 

menu program 60-61, 137-138, 141 

message program 34, 141 

modifying programs 99-1 1 1 

moving the cursor 23-24 

N 

naming programs 19 
nested loops 37 

New Print command 4, 42, 95, 125 
newcalc program 68-69,141 
No Display command 11,44-45, 

110,125 
number program 71, 141 
numeric variables 

accumulators 67-68 

calculating with 66-69 

commands 126 

comparing numeric variables 

68-69 

converting strings to 66-67 
counters 67-68 
definition of 50, 65 
giving an initial value to 68 
Set X, Y and Z commands 66, 
126 

syntax of 117 
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o 

output destination 60-61,137-138 
overflow 65 

P 

pick program 53, 141 
Print command 42, 45, 124 
print value files 61, 138-139 
printing from programs 42, 60 
printing to screen 42-44, 60 
processing loops 96-98 
program loops 35-37 
prtval program 138-139,142 

Q 

Quit command 34, 37, 123 

R 

replacing text 25,28,75 
Return command 81,124 
re turn fr om subroutines 81, 124 

(RETURN) 116 

s 

Save command 18,41 
savepart program 41.141 
screen 

and debugging 12 

clearing 45 

controlling display 44-45 
Input command 43,44,52.124 
No Display command 1 1 , 44-45, 
110, 125 

Print command 42, 45, 124 
printing to 42-44, 60, 137-138 
sending output to 42^44, 60, 1 37-1 38 
sharing with Apple Writer 1 1 
text display 11-12 
Yes Display command 11,45,125 

setting variables 52-57 

Set X, Y and Z commands 66,126 

star program 28-29,135 

startgloss program 85, 142 

startup program 84-86 

statements 

See WPL statements 

string variables 

Assign String command 54, 55, 
68, 127 

commands 126-127 
Compare Strings command 
58-60,127 



concatenating 54-55 
definition of 49-51 
generalizing programs with 53 
Load String command 56-57, 58, 
127 

setting 52-57 
syntax of 117 
strings 49 

Subroutine Call command 80-81 . 
123 

subroutines 80-82,123-124 
syntax 

definition of 15 

of a WPL statement 19-21, 

115-117 

system print (sys.prt) file 84, 86 
system tab (SYS . tab) file 84, 86 



testing program changes 109-1 1 1 

text buffer 11,44-45,56 

text display 11-12 

trace 132-133 

transfer of control 80, 81 



unsuccessful outcome 57 
uppercase characters 18, 50, 136 
using programs 19 
UTILITIES disk 3,4,19,111,141 

V 

variables 

See numeric variables and string 
variables 

w 

workfiles 102-103 
WPL commands 

definition of 16 

how to recognize 9 

how to write 16, 26, 116 

list of 119 

summary by function 121-127 
WPL statements 

definition of 17 

how to write 22 

syntax of 19-21,115-117 
write program 72-75, 141 

Yes Display command 11,45,125 



Index 



147 



apple computer 

" 20525 Mariani Avenue 
Cupertino, California 95014 
(408) 996-1010 
TLX 171-576 
030-0601 -A 



